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';
// 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, 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 {}

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

    Angular Tooltip の使用

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

    // 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 {}

    ツールチップ ターゲット

    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 デモ セクションで示されるデモサンプルを確認することができます。

    設定の表示/非表示

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

    Note

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

    オーバーレイ構成

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

    高機能なツールチップ

    コンテンツのカスタマイズやスタイル設定が igxTooltip ディレクティブで簡単にできます。ツールチップはマークアップの標準要素であるため、必要な要素を追加してコンテンツを改善や状況に応じたスタイル設定が可能です。

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

    // 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 {}

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

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

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

    スタイル設定

    ツールチップのスタイル設定は、すべてのテーマ関数とコンポーネント ミックスインが存在する 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>

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

    @include css-vars($dark-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 は以下の通りです。

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

    スタイル:

    その他のリソース

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