Angular Tooltip (ツールチップ) ディレクティブの概要

    igxTooltip と igxTooltipTarget ディレクティブは、完全なカスタマイズが可能なツールチップをサポートし、ページのあらゆる要素にアタッチできます。 ツールチップは、igxTooltipTargetディレクティブで使用できる場所の数が限られています。ターゲット (アンカー) と関連つけてページで任意の配置を指定でき、スクロールやカスタム アニメーションなどのその他のオーバーレイ設定をサポートします。

    Angular Tooltip の例

    Ignite UI for Angular Tooltip を使用した作業の開始

    Ignite UI for Angular Tooltip ディレクティブを使用した作業を開始するには、Ignite UI for Angular をインストールする必要があります。既存の Angular アプリケーションで、以下のコマンドを入力します。

    ng add igniteui-angular

    Ignite UI for Angular については、「はじめに」トピックをご覧ください。

    次に、app.module.ts ファイルに IgxTooltipModule をインポートします。

    // app.module.ts

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

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

    あるいは、16.0.0 以降、IgxTooltipDirective をスタンドアロンの依存関係としてインポートすることも、IGX_TOOLTIP_DIRECTIVES トークンを使用してコンポーネントとそのすべてのサポート コンポーネントおよびディレクティブをインポートすることもできます。

    // home.component.ts

import { IGX_TOOLTIP_DIRECTIVES } from 'igniteui-angular/tooltip';
import { IgxAvatarComponent } from 'igniteui-angular/avatar';
// 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 {}

    Ignite UI for Angular Tooltip モジュールまたはディレクティブをインポートしたので、igxTooltip ディレクティブの使用を開始できます。

    Angular Tooltip の使用

    上記のようにシンプルなテキスト ツールチップを作成します。IgxAvatarModule をインポートして要素として IgxAvatar を使用します。

    // app.module.ts

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

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

    ツールチップ ターゲット

    avatar をターゲットにして、igxTooltipTarget ディレクティブを設定し、ツールチップを持つ要素としてマークします。

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

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

    ツールチップ

    ツールチップ要素を作成します。シンプルなテキスト ツールチップを作成するためテキストを含む標準 div 要素を定義し、ツールチップとしてマークされる igxTooltip ディレクティブを設定します。

    • igxTooltip ディレクティブは igxToggle ディレクティブを拡張します。
    • igxTooltip ディレクティブは、名前 tooltip でエクスポートされます。
    <!--simpleTooltip.component.html-->

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

    ツールチップをターゲットにアタッチ

    ここまででターゲットとツールチップを定義しました。ツールチップ参照を igxTooltipTarget セレクターに割り当てます。

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

    すべて適切に設定できると、Tooltip デモ セクションで示されるデモサンプルを確認することができます。

    高機能なツールチップ

    ツールチップのコンテンツは単なるテキスト以上のものになります。ツールチップはマークアップ内の通常の要素であるため、必要な要素を追加し、それに応じてスタイルを設定することで、そのコンテンツを強化できます。

    igxTooltip を活用し、マップの特定の場所について詳細な情報を提供します。単純な div を使用してマップを表示し、ツールチップのロゴに IgxAvatar、マップの場所アイコンに IgxIcon を使用します。この目的のためには、各モジュールを取得する必要があります。

    // app.module.ts

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

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

    アプリケーションには以下のスタイルを使用します。

    /* 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;
}

    マップを作成しましょう。マップの背景画像がある単純な div を使用します。更に場所の配置を示すアイコンを追加します。場所の詳細を提供するためにアイコンがツールチップのターゲットになります。

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

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

    次にツールチップを作成します。コンテンツは、テキスト情報要素とアバターで構成されるコンテナーを作成します。ツールチップをターゲットにアタッチして CSS スタイルを使用します。

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

    上記をすべて完了すると場所とツールチップは以下のようになります。

    高度な例

    ツールチップは他のコンポーネントとシームレスに統合され、内部にコンポーネントを含む高度なツールチップを作成できます。次の例では、IgxList、IgxAvatar、IgxIcon、IgxBadge、IgxButton、IgxCard および IgxCategoryChart コンポーネントを使用して説明的なツールチップを作成する方法を示しています。

    遅延の表示/非表示の設定

    ツールチップを表示または非表示にするまでの時間を制御する場合は、igxTooltipTarget ディレクティブの showDelay と hideDelay プロパティを使用します。両プロパティは型 number でミリセカンドでタイムスパンを取得できます。

    Note

    IgxTooltipTargetDirective の組み込み UI インタラクションは、showDelay および hideDelay プロパティの値を考慮して動作します。一方で、API からツールチップを表示または非表示にする場合や IgxTooltipDirective の API を使用する場合、showDelay や hideDelay は考慮されません。必要な場合、ロジックはアプリケーションの仕様を手動で実装する必要があります。

    トリガー

    デフォルトでは、igxTooltip は igxTooltipTarget 上にホバーしている間のみトリガーされます。ただし、showTriggers および hideTriggers プロパティを使用してこの動作を変更できます。これらのプロパティにより、igxTooltip が表示および非表示になるタイミングを制御できます。これらのプロパティは click、focus、keypress などのイベント名を値として受け取り、さまざまなシナリオで igxTooltip をトリガーできます。

    Note

    showTriggers および hideTriggers の設定は、igxTooltip 自体ではなく igxTooltipTarget とのインタラクション時にのみ有効です。igxTooltip のデフォルトのイベント トリガーは pointerenter および pointerleave です。

    オーバーレイ構成

    igxTooltip と igxTooltipTarget の両ディレクティブは、内部的に IgxOverlayService を使用してツールチップ要素を開閉します。

    igxTooltipTarget ディレクティブは positionSettings プロパティを公開しており、ツールチップのアニメーション、UI 上での配置などをカスタマイズできます。未設定の場合はデフォルトの配置設定が適用されます。

    さらに詳細なカスタマイズには、igxToggleAction から継承された overlaySettings プロパティを使用します。

    <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

    positionSettings または overlaySettings で設定したプロパティは、デフォルト設定の同じプロパティをオーバーライドし、ツールチップの動作に直接影響します。

    追加のプロパティ

    これまでに説明したプロパティの他に、igxTooltipTarget ではツールチップの動作や外観をさらに構成できるさまざまな追加プロパティが用意されています。

    sticky プロパティを有効にするとツールチップが「固定」され、閉じるボタンが表示されます。ユーザーが閉じるボタンをクリックするか Esc キーを押すまでツールチップは表示されたままになります。この動作はデフォルトのホバー挙動をオーバーライドし、ターゲット要素からカーソルを外してもツールチップが消えなくなります。

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

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

    デフォルトの閉じるボタンをカスタマイズするには、closeButtonTemplate プロパティを使用します。

    
<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

    closeButtonTemplate で追加したカスタム コンテンツは、sticky モードのときのみレンダリングされます。

    hasArrow プロパティを使用すると、ツールチップに矢印を追加できます。

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

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

    矢印要素は、指定された配置設定に基づいて配置されます。方向や開始点が定義済みの配置値に一致しない場合、矢印はツールチップの上部中央側に配置されます (デフォルトのツールチップの配置は bottom)。

    定義済みの配置値

    配置 水平方向 水平開始点 垂直方向 垂直開始点
    top HorizontalAlignment.Center HorizontalAlignment.Center VerticalAlignment.Top VerticalAlignment.Top
    top-start HorizontalAlignment.Right HorizontalAlignment.Left VerticalAlignment.Top VerticalAlignment.Top
    top-end HorizontalAlignment.Left HorizontalAlignment.Right VerticalAlignment.Top VerticalAlignment.Top
    bottom HorizontalAlignment.Center HorizontalAlignment.Center VerticalAlignment.Bottom VerticalAlignment.Bottom
    bottom-start HorizontalAlignment.Right HorizontalAlignment.Left VerticalAlignment.Bottom VerticalAlignment.Bottom
    bottom-end HorizontalAlignment.Left HorizontalAlignment.Right VerticalAlignment.Bottom VerticalAlignment.Bottom
    right HorizontalAlignment.Right HorizontalAlignment.Right VerticalAlignment.Middle VerticalAlignment.Middle
    right-start HorizontalAlignment.Right HorizontalAlignment.Right VerticalAlignment.Bottom VerticalAlignment.Top
    right-end HorizontalAlignment.Right HorizontalAlignment.Right VerticalAlignment.Top VerticalAlignment.Bottom
    left HorizontalAlignment.Left HorizontalAlignment.Left VerticalAlignment.Middle VerticalAlignment.Middle
    left-start HorizontalAlignment.Left HorizontalAlignment.Left VerticalAlignment.Bottom VerticalAlignment.Top
    left-end HorizontalAlignment.Left HorizontalAlignment.Left VerticalAlignment.Top VerticalAlignment.Bottom

    次の例では、すべての配置オプションと矢印の配置動作の実際のデモを見ることができます。

    矢印の配置をカスタマイズする

    矢印の配置をカスタマイズするには、positionArrow(arrow: HTMLElement, arrowFit: ArrowFit) メソッドをオーバーライドできます。

    例:

    export class CustomStrategy extends TooltipPositionStrategy {
  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>

    スタイル設定

    ツールチップのスタイル設定は、すべてのテーマ関数とコンポーネント ミックスインが存在する index ファイルをインポートする必要があります。

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

// 重要: Ignite UI for Angular 13 より前のバージョンは、次を使用してください。
// @import '~igniteui-angular/lib/core/styles/themes/index';

    最もシンプルな方法として、tooltip-theme を拡張する新しいテーマを作成し、$text-color、$background、$border-radius パラメーターを指定します。

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

    ダイアログ ウィンドウのコンテンツの一部として使用される追加コンポーネント (IgxButton、IgxSwitch など) をスタイルするには、それぞれのコンポーネントに固有の追加テーマを作成し、ツールチップのスコープ内のみに配置する必要があります (残りのアプリケーションの影響を受けません)。

    ツールチップは IgxOverlayService を使用するため、スタイル設定するツールチップにカスタム テーマが適用されるよう、ダイアログ ウィンドウが表示されたときに DOM に配置される特定のアウトレットを提供します。

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

    最後にコンポーネントのテーマをアプリケーションに含めます。

    :host {
  @include tokens($dark-tooltip);
}

    スタイル設定されたツールチップは以下のようになります。

    デモ

    Tailwind によるスタイル設定

    カスタム Tailwind ユーティリティ クラスを使用して tooltip をスタイル設定できます。まず Tailwind を設定してください。

    グローバル スタイルシートに Tailwind をインポートした上で、以下のように必要なテーマ ユーティリティを適用します:

    @import "tailwindcss";
...
@use 'igniteui-theming/tailwind/utilities/material.css';

    ユーティリティ ファイルには、light テーマと dark テーマの両方のバリエーションが含まれています。

    • light-* クラスはライト テーマ用です。
    • dark-* クラスはダーク テーマ用です。
    • プレフィックスの後にコンポーネント名を追加します (例: light-tooltip、dark-tooltip)。

    これらのクラスを適用すると、動的なテーマの計算が可能になります。 任意のプロパティを使用して、生成された CSS 変数をオーバーライドできます。 コロンの後に、有効な CSS カラー形式 (HEX、CSS 変数、RGB など) を指定します。

    プロパティの完全なリストは、IgxTooltip テーマ で確認できます。構文は次のとおりです:

    <div
  class="!light-tooltip ![--background:#90B69F]"
  #tooltipRef="tooltip"
  igxTooltip>
  Her name is Madelyn James
</div>
    Note

    ユーティリティ クラスが優先されるようにするには、感嘆符 (!) が必要です。Tailwind はスタイルをレイヤーに適用しますが、これらのスタイルを重要としてマークしないと、コンポーネントのデフォルトのテーマによってオーバーライドしてしまいます。

    最終的に、tooltip は次のようになります:

    ユーザー補助

    igxTooltip はアクセシビリティを考慮して構築されており、以下のプロパティや ARIA 属性が含まれています。

    • id プロパティ - 開発者が設定しない場合、自動生成されます。
    • role - ツールチップがデフォルトの動作になっている場合、role="tooltip" が適用されます。sticky プロパティが有効な場合、ロールは status に変更されます。
    • aria-hidden - ツールチップが表示されているかどうかに応じて自動的に更新されます。

    ターゲットの aria-describedby 属性をそれぞれのツールチップの id に設定することにより、ツールチップ要素への参照が提供されます。エンドユーザーがツールチップへアクセスしたときにツールチップのコンテンツにアクセスするために必要な情報であるスクリーン リーダーを提供します。

    以下の状況では十分な注意が必要です。

    • ツールチップのコンテンツは非常に複雑なため自動翻訳できません。
    • ツールチップは、ビルトインではなく手動で実装された動作とともに使用されます (手動による表示/非表示など)。
    • ターゲット要素はフォーカスできません。

    注意と制限

    制限 説明
    カスタム配置ストラテジと矢印 igxTooltipTarget ディレクティブは TooltipPositionStrategy を使用してツールチップと矢印を配置します。カスタムの positionStrategy を使用する場合、かつ hasArrow を true に設定する場合、そのカスタム ストラテジは TooltipPositionStrategy を継承している必要があります。そうでない場合、矢印は表示されません。

    API リファレンス

    このトピックでは、ページ要素にツールチップを作成する方法について学習しました。アプリケーションのデザインを改善するために、アイコンやアバターなどその他の Ignite UI for Angular コンポーネントも使用しました。各 API は以下の通りです。

    使用したその他のコンポーネントとディレクティブ:

    スタイル:

    その他のリソース

    コミュニティに参加して新しいアイデアをご提案ください。