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.

• A diretiva igxTooltipTarget estende a diretiva igxToggleAction.
• A diretiva igxTooltipTarget é exportada com o nome tooltipTarget.

<!--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.

• A diretiva igxTooltip estende a diretiva igxToggle.
• A diretiva igxTooltip é exportada com o nome 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 interface do usuário interno dos IgxTooltipTargetDirective trabalhos levando showDelay em conta os valores de propriedade e hideDelay. Mostrar e ocultar a dica de ferramenta por meio da API ou da API do NÃO leva em conta os showDelay valores da IgxTooltipDirective propriedade and hideDelay. Se necessário, essa lógica teria que ser implementada manualmente de acordo com as especificidades do aplicativo.

Overlay configuration

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

A igxTooltipTarget diretiva expõe uma positionSettings propriedade, que pode ser usada para personalizar as animações de nossa dica de ferramenta, sua posição na interface do usuário e muito mais! Se essa propriedade não estiver definida, as configurações de posição padrão serão usadas.

Para personalizar ainda mais a dica de ferramenta, use a overlaySettings propriedade (herdada do igxToggleAction).

<igx-icon [igxTooltipTarget]="tooltipRef" [positionSettings]="positionSettings" [overlaySettings]="overlaySettings">
  info
</igx-icon>

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

public positionSettings: PositionSettings = {
  horizontalDirection: HorizontalAlignment.Left,
  horizontalStartPoint: HorizontalAlignment.Left,
  verticalDirection: VerticalAlignment.Top,
  verticalStartPoint: VerticalAlignment.Bottom,
  openAnimation: useAnimation(slideInTop, { params: { duration: '2000ms' } }),
  closeAnimation: useAnimation(slideOutBottom, { params: { duration: '2000ms'} }),
  offset: 10
}

public overlaySettings: OverlaySettings = {
  closeOnEscape: false,
};

Note

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

Additional Properties

Além das propriedades que já abordamos, o oferece igxTooltipTarget uma variedade de propriedades adicionais que permitem configurar ainda mais o comportamento e a aparência da dica de ferramenta.

Você pode tornar a dica de ferramenta "fixa" usando a sticky propriedade, que adiciona um botão Fechar e mantém a dica de ferramenta visível até que o usuário a feche manualmente - clicando no botão Fechar ou pressionando a Esc tecla. Esse comportamento substitui o comportamento de foco padrão, impedindo que a dica de ferramenta desapareça quando o usuário parar de passar o mouse sobre o elemento de destino.

<igx-icon [igxTooltipTarget]="tooltipRef" [sticky]="true">
  info
</igx-icon>

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

Para personalizar o botão de fechamento padrão, use a closeButtonTemplate propriedade.

<igx-icon [igxTooltipTarget]="tooltipRef" [sticky]="true" [closeButtonTemplate]="customTemplate">
  info
</igx-icon>

<ng-template #customTemplate>
  <igx-icon>cancel</igx-icon>
</ng-template>

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

Note

Qualquer conteúdo personalizado adicionado por meio do closeButtonTemplate é renderizado somente quando a dica de ferramenta está no modo fixo.

Além disso, você pode adicionar um indicador de seta à dica de ferramenta usando a hasArrow propriedade.

<igx-icon [igxTooltipTarget]="tooltipRef" [hasArrow]="true">
  info
</igx-icon>

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

O elemento de seta é posicionado com base nas configurações de posição fornecidas. Se as direções e os pontos iniciais não corresponderem a nenhum dos valores de posição predefinidos, a seta será posicionada no lado central superior da dica de ferramenta (posição bottom padrão da dica de ferramenta).

Valores de posição predefinidos

Posição	Direção horizontal	Ponto de partida horizontal	Direção vertical	Ponto de partida vertical
principal	AlinhamentoHorizontal.Centro	AlinhamentoHorizontal.Centro	VerticalAlignment.Top	VerticalAlignment.Top
começo de primeira	AlinhamentoHorizontal.Direita	AlinhamentoHorizontal.Esquerda	VerticalAlignment.Top	VerticalAlignment.Top
topo de gama	AlinhamentoHorizontal.Esquerda	AlinhamentoHorizontal.Direita	VerticalAlignment.Top	VerticalAlignment.Top
fundo	AlinhamentoHorizontal.Centro	AlinhamentoHorizontal.Centro	AlinhamentoVertical.Bottom	AlinhamentoVertical.Bottom
começo de baixo	AlinhamentoHorizontal.Direita	AlinhamentoHorizontal.Esquerda	AlinhamentoVertical.Bottom	AlinhamentoVertical.Bottom
extremidade inferior	AlinhamentoHorizontal.Esquerda	AlinhamentoHorizontal.Direita	AlinhamentoVertical.Bottom	AlinhamentoVertical.Bottom
Certo	AlinhamentoHorizontal.Direita	AlinhamentoHorizontal.Direita	AlinhamentoVertical.Meio	AlinhamentoVertical.Meio
início direito	AlinhamentoHorizontal.Direita	AlinhamentoHorizontal.Direita	AlinhamentoVertical.Bottom	VerticalAlignment.Top
extremidade direita	AlinhamentoHorizontal.Direita	AlinhamentoHorizontal.Direita	VerticalAlignment.Top	AlinhamentoVertical.Bottom
Esquerda	AlinhamentoHorizontal.Esquerda	AlinhamentoHorizontal.Esquerda	AlinhamentoVertical.Meio	AlinhamentoVertical.Meio
início esquerdo	AlinhamentoHorizontal.Esquerda	AlinhamentoHorizontal.Esquerda	AlinhamentoVertical.Bottom	VerticalAlignment.Top
extremidade esquerda	AlinhamentoHorizontal.Esquerda	AlinhamentoHorizontal.Esquerda	VerticalAlignment.Top	AlinhamentoVertical.Bottom

Personalizando a posição da seta

Para personalizar a posição da seta, você pode substituir o positionArrow(arrow: HTMLElement, arrowFit: ArrowFit) método.

Por exemplo:

export class CustomStrategy extends TooltipPositioningStrategy {
  constructor(settings?: PositionSettings) {
    super(settings);
  }

  public override positionArrow(arrow: HTMLElement, arrowFit: ArrowFit): void {
    Object.assign(arrow.style, {
      left: '-0.25rem',
      transform: 'rotate(-45deg)',
      [arrowFit.direction]: '-0.25rem',
    });
  }
}

public overlaySettings: OverlaySettings = {
  positionStrategy: new CustomStrategy({
    horizontalDirection: HorizontalAlignment.Right,
    horizontalStartPoint: HorizontalAlignment.Right,
    verticalDirection: VerticalAlignment.Bottom,
    verticalStartPoint: VerticalAlignment.Bottom,
  })
};

<igx-icon [igxTooltipTarget]="tooltipRef" [hasArrow]="true" [overlaySettings]="overlaySettings">
  info
</igx-icon>

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

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:

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 fornece os $text-color parâmetros. $background​ ​$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

O igxTooltip é construído com acessibilidade em mente e inclui as seguintes propriedades e atributos ARIA:

• id property - gerado automaticamente se não for definido pelo desenvolvedor.
• role- Quando a dica de ferramenta está em seu comportamento padrão, role="tooltip" é aplicada. Se a sticky propriedade estiver habilitada, a função será alterada para status.
• aria-hidden- Atualizado automaticamente dependendo se a dica de ferramenta está visível ou não.

Ao definir o atributo aria-describedby do destino para suas respectivas dicas de id ferramenta, uma referência será fornecida ao elemento de dica de ferramenta. Isso fornece aos leitores de tela as informações necessárias para ler o conteúdo da dica de ferramenta quando o usuário final aciona a dica de ferramenta.

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.

Notes and Limitations

Limitação	Descrição
Estratégia de posição personalizada com seta	AigxTooltipTarget diretiva usa oTooltipPositionStrategy para posicionar a dica de ferramenta e o elemento de seta. Se um costumepositionStrategy for usado ehasArrow definido comotrue, a estratégia personalizada deverá estender oTooltipPositionStrategy. Caso contrário, a seta não será exibida.

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:

• IgxTooltipDiretiva
• IgxTooltipTargetDirectiva

Componentes e/ou diretivas adicionais que foram usados:

• Componente IgxAvatar
• Componente IgxIcon
• IgxToggleDirectiva
• IgxToggleActionDirectiva

Styles:

• Estilos de IgxTooltipDirective
• Estilos de componentes IgxAvatar
• Estilos IgxIconComponent

Additional Resources

Nossa comunidade é ativa e sempre acolhedora para novas ideias.

• Ignite UI for Angular Fóruns
• Ignite UI for Angular GitHub