Visão geral da diretiva Angular Tooltip

    As diretivas igxTooltip e igxTooltipTarget nos fornecem a capacidade de criar uma dica de ferramenta totalmente personalizável e anexá-la a qualquer elemento em nossa página. Enquanto a maioria das dicas de ferramenta tem um número limitado de posições disponíveis, com a diretiva igxTooltipTarget podemos especificar qualquer posição que quisermos na página, mantendo-a em relação ao alvo (âncora) e fornecer várias outras configurações de sobreposição, como estratégias de rolagem e animações personalizadas!

    Angular Tooltip Example

    Getting Started with Ignite UI for Angular Tooltip

    Para começar a usar a diretiva Ignite UI for Angular Tooltip, primeiro você precisa instalar Ignite UI for Angular. Em um aplicativo Angular existente, digite o seguinte comando:

    ng add igniteui-angular

    Para obter uma introdução completa ao Ignite UI for Angular, leia o tópico de introdução.

    O próximo passo é importar o IgxTooltipModule no seu arquivo app.module.ts.

    // app.module.ts

...
import { IgxTooltipModule } from 'igniteui-angular';
// import { IgxTooltipModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    ...
    imports: [IgxTooltipModule],
})
export class AppModule {}

    Como alternativa, a partir da 16.0.0 você pode importar o IgxTooltipDirective como uma dependência autônoma ou usar o token IGX_TOOLTIP_DIRECTIVES para importar o componente e todos os seus componentes e diretivas de suporte.

    // home.component.ts

import { IGX_TOOLTIP_DIRECTIVES, IgxAvatarComponent } from 'igniteui-angular';
// import { IGX_TOOLTIP_DIRECTIVES, IgxAvatarComponent } from '@infragistics/igniteui-angular'; for licensed package

@Component({
  selector: 'app-home',
  template: `
    <igx-avatar
      class="avatar"
      #target="tooltipTarget"
      [igxTooltipTarget]="tooltipRef"
      src="assets/images/avatar/10.jpg"
      size="medium"
      shape="circle"
    >
    </igx-avatar>

    <div #tooltipRef="tooltip" igxTooltip>Her name is Madelyn James</div>
  `,
  styleUrls: ['home.component.scss'],
  standalone: true,
  imports: [IGX_TOOLTIP_DIRECTIVES, IgxAvatarComponent],
  /* or imports: [IgxTooltipDirective, IgxTooltipTargetDirective, IgxAvatarComponent] */
})
export class HomeComponent {}

    Agora que você importou o módulo ou as diretivas do Ignite UI for Angular Tooltip, você pode começar a usar a diretiva igxTooltip.

    Using the Angular Tooltip

    Digamos que queremos criar uma dica de ferramenta de texto simples como a acima. No nosso caso, estamos usando nosso incrível IgxAvatar como o elemento, então começamos importando o IgxAvatarModule primeiro.

    // app.module.ts

import { IgxTooltipModule, IgxAvatarModule } from 'igniteui-angular';
// import { IgxTooltipModule, IgxAvatarModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    ...
    imports: [IgxTooltipModule, IgxAvatarModule],
})
export class AppModule {}

    Tooltip target

    O avatar será nosso alvo e tudo o que precisamos fazer é definir a diretiva igxTooltipTarget nele, o que basicamente marca nosso elemento como aquele que tem uma dica de ferramenta.

    <!--simpleTooltip.component.html-->

<igx-avatar
  class="avatar"
  #target="tooltipTarget"
  igxTooltipTarget
  src="assets/images/avatar/10.jpg"
  size="medium"
  shape="circle">
</igx-avatar>

    Dica de ferramenta

    Agora vamos criar o elemento tooltip em si! Como queremos um tooltip de texto simples, definiremos um elemento div comum com texto dentro e definiremos a diretiva igxTooltip nele, que o marca como um tooltip.

    <!--simpleTooltip.component.html-->

<div #tooltipRef="tooltip" igxTooltip>Her name is Madelyn James</div>

    Attach tooltip to target

    Agora que definimos nosso alvo e a dica de ferramenta, tudo o que nos resta fazer é atribuir a referência da dica de ferramenta ao seletor igxTooltipTarget do alvo.

    <!--simpleTooltip.component.html-->

<igx-avatar
  class="avatar"
  #target="tooltipTarget"
  [igxTooltipTarget]="tooltipRef"
  src="assets/images/avatar/10.jpg"
  size="medium"
  shape="circle">
</igx-avatar>

<div #tooltipRef="tooltip" igxTooltip>Her name is Madelyn James</div>

    Se tudo correr bem, você deverá ver o exemplo mostrado na seção Demonstração de dica de ferramenta.

    Show/Hide delay settings

    E se quisermos controlar a quantidade de tempo que deve passar antes de mostrar e ocultar a dica de ferramenta? Para esse propósito, podemos usar as propriedades showDelay e hideDelay da diretiva igxTooltipTarget. Ambas as propriedades são do tipo number e levam tempo em milissegundos.

    Note

    O comportamento de interação da IU interna do IgxTooltipTargetDirective e seus respectivos métodos de API funcionam levando em conta os valores das propriedades showDelay e hideDelay. Mostrar e ocultar a dica de ferramenta por meio da API do IgxTooltipDirective não leva em conta os valores das propriedades showDelay e hideDelay. Se necessário, essa lógica teria que ser implementada manualmente de acordo com as especificações do aplicativo.

    Rich tooltip

    Personalizar e estilizar o conteúdo da nossa tooltip nunca foi tão fácil com a diretiva igxTooltip! Como a tooltip em si é um elemento comum na nossa marcação, podemos basicamente melhorar seu conteúdo adicionando quaisquer elementos que precisamos e ter a capacidade de estilizá-los de acordo!

    Vamos expandir o uso do igxTooltip e usá-lo para fornecer mais detalhes para um local específico em um mapa! Usaremos um div simples para representar nosso mapa, o IgxAvatar para um logotipo em nossa dica de ferramenta e o IgxIcon para o ícone de localização em nosso mapa. Para esse propósito, obteremos seus respectivos módulos.

    // app.module.ts

import { IgxTooltipModule, IgxAvatarModule, IgxIconModule } from 'igniteui-angular';
// import { IgxTooltipModule, IgxAvatarModule, IgxIconModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    ...
    imports: [IgxTooltipModule, IgxAvatarModule, IgxIconModule],
})
export class AppModule {}

    Também usaremos os seguintes estilos para nossa aplicação:

    /* richTooltip.component.css */

.location:hover {
  cursor: pointer;
}

.map {
  overflow: hidden;
  display: flex;
  align-items: center;
  justify-content: center;
  width: 200px;
  height: 252px;
  background-image: url(assets/images/card/media/infragisticsMap.png);
  border: 1px solid #d4d4d4;
}

.locationTooltip {
  width: 310px;
  background-color: var(--igx-grays-700);
  padding: 3px;
  font-size: 13px;
}

.locationTooltipContent {
  display: flex;
  justify-content: center;
  align-items: center;
}

.logo {
  margin-right: 10px;
  min-width: 25px;
  width: 45px;
  height: 45px;
}

    Vamos começar criando nosso mapa. Precisamos de um div simples que tenha como plano de fundo uma imagem com um mapa. Além disso, adicionaremos um ícone que indicará a posição da nossa localização! Como queremos fornecer mais detalhes para essa localização, nosso ícone obviamente será o alvo da dica de ferramenta.

    <!--richTooltip.component.html-->

<div class="map">
  <igx-icon
    class="location"
    [style.color]="'blue'"
    fontSet="material"
    [igxTooltipTarget]="locationTooltip"
    >location_on</igx-icon>
  ...
</div>

    Agora para a dica de ferramenta! Para seu conteúdo, criaremos um contêiner que será preenchido com alguns elementos de informação de texto e um avatar. Então, simplesmente anexaremos a dica de ferramenta ao alvo e incluiremos um estilo CSS bacana!

    <!--richTooltip.component.html-->

<div class="wrapper">
  <div class="map">
    <igx-icon
      class="location"
      [style.color]="'blue'"
      fontSet="material"
      [igxTooltipTarget]="locationTooltip"
      >location_on</igx-icon>

    <div class="locationTooltip" #locationTooltip="tooltip" igxTooltip>
      <div class="locationTooltipContent">
        <igx-avatar
          class="logo"
          src="assets/images/card/avatars/igLogo.png"
          size="medium"
          shape="square">
        </igx-avatar>
        <div>
          <div>Infragistics Inc. HQ</div>
          <div>2 Commerce Dr, Cranbury, NJ 08512, USA</div>
        </div>
      </div>
    </div>
  </div>
</div>

    Se tudo correr bem, é assim que nossa localização e dica de ferramenta devem ficar:

    Overlay configuration

    As diretivas igxTooltip e igxTooltipTarget usam o IgxOverlayService para abrir e fechar o respectivo elemento de dica de ferramenta.

    A diretiva igxTooltipTarget expõe uma propriedade overlaySettings (herdada de igxToggleAction), que pode ser usada para personalizar as animações da nossa dica de ferramenta, sua posição na UI e muito mais! Se essa propriedade não for definida, as configurações de sobreposição padrão serão usadas.

    Note

    Qualquer propriedade definida por meio de overlaySettings substituirá a mesma propriedade das configurações de sobreposição padrão e terá um impacto direto na dica de ferramenta.

    Estilização

    Para começar a estilizar a dica de ferramenta, precisamos importar o arquivo index, onde todas as funções do tema e mixins de componentes estão localizados:

    @use "igniteui-angular/theming" as *;

// IMPORTANT: Prior to Ignite UI for Angular version 13 use:
// @import '~igniteui-angular/lib/core/styles/themes/index';

    Seguindo a abordagem mais simples, criamos um novo tema que estende o tooltip-theme e aceita os parâmetros $text-color, $background e $border-radius.

    $dark-tooltip: tooltip-theme(
  $text-color: #ecaa53,
  $background: #011627,
  $border-radius: 6px,
);
    Note

    Para estilizar quaisquer componentes adicionais que são usados como parte do conteúdo da dica de ferramenta (como IgxButton, IgxSwitch, etc.), um tema adicional deve ser criado, específico para o respectivo componente e colocado somente no escopo da dica de ferramenta (para que não afete o restante do aplicativo).

    Como a dica de ferramenta usa o IgxOverlayService, para que nosso tema personalizado alcance a dica de ferramenta que queremos estilizar, forneceremos uma saída específica onde a dica de ferramenta será colocada no DOM quando estiver visível.

    <igx-avatar
  #target="tooltipTarget"
  [igxTooltipTarget]="tooltipRef"
  [igxToggleOutlet]="outlet"
>
</igx-avatar>

<div #outlet="overlay-outlet" igxOverlayOutlet>
  <div #tooltipRef="tooltip" igxTooltip>Her name is Madelyn James</div>
</div>

    O último passo é incluir o tema do componente em nosso aplicativo.

    @include css-vars($dark-tooltip);

    Agora nossa dica de ferramenta estilizada deve ficar assim:

    Demo

    Accessibility

    Elementos com a diretiva igxTooltip têm uma propriedade id gerada automaticamente (se não definida pelo desenvolvedor), uma role tooltip e o atributo aria-hidden que é atualizado automaticamente dependendo se a tooltip está visível ou não. Ao definir o atributo aria-describedby do alvo para o id da respectiva tooltip, uma referência será fornecida ao elemento tooltip. Isso fornece aos leitores de tela as informações necessárias para ler o conteúdo da tooltip quando o usuário final aciona a tooltip.

    Cuidado extra deve ser tomado nos seguintes cenários:

    • O conteúdo da dica de ferramenta é muito complexo para ser interpretado automaticamente.
    • A dica de ferramenta é usada com um comportamento implementado manualmente (por exemplo, mostrar/ocultar manualmente) em vez do comportamento integrado.
    • O elemento alvo não pode ser focado.

    API References

    Neste artigo, aprendemos como criar, configurar e estilizar dicas de ferramentas incríveis para os elementos em nossa página! Também usamos alguns componentes adicionais Ignite UI for Angular como ícones e avatares, para melhorar o design do nosso aplicativo! As respectivas APIs estão listadas abaixo:

    Componentes e/ou diretivas adicionais que foram usados:

    Styles:

    Additional Resources

    Nossa comunidade é ativa e sempre acolhedora para novas ideias.