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
ディレクティブを設定し、ツールチップを持つ要素としてマークします。
igxTooltipTarget
ディレクティブはigxToggleAction
ディレクティブを拡張します。igxTooltipTarget
ディレクティブは、名前 tooltipTarget でエクスポートされます。
<!--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 は以下の通りです。
使用したその他のコンポーネントとディレクティブ:
スタイル: