Power BI カスタムビジュアル開発 : TooltipUtils でツールティップを活用する

TooltipUtils

TooltipUtils は PowerBI カスタムビジュアルで使えるツールティップをシンプルにする機能を提供します。本体ツールティップを出すためには ツールティップと多言語サポート で紹介したように、チャートの各要素に対して mouseover イベントの処理をコーディングする必要がありますが、このユーティリティーを使えば省略可能です。

インストール

以下手順で追加。

1. npm コマンドでインストール。

npm install powerbi-visuals-utils-tooltiputils --save

2. tsconfig.json の files に型情報を追加。

tsconfig.json

{
  "compilerOptions": {
  ...
  },
  "files": [
    ...,　
    "node_modules/powerbi-visuals-utils-tooltiputils/lib/index.d.ts"
  ]
}

3. pbiviz.json の externalJS に追加。

pbiviz.json

{
  ...
  "externalJS": [
    ...,
    "node_modules/powerbi-visuals-utils-tooltiputils/lib/index.js"
  ],
  ...
}

機能

• [TooltipService](#tooltipservices] : ツールティップの操作を簡単にするサービス

TooltipService

TooltipService はカスタムビジュアルのツールティップの操作を簡単にします。

powerbi.extensibility.utils.tooltip モジュールでは以下の機能を提供します。

• createTooltipServiceWrapper
• addTooltip

createTooltipServiceWrapper

この関数で ITooltipServiceWrapper のインスタンスを作成

function createTooltipServiceWrapper(tooltipService: ITooltipService, rootElement: Element, handleTouchDelay?: number): ITooltipServiceWrapper;

createTooltipServiceWrapper の例

import tooltip = powerbi.extensibility.utils.tooltip;
...

export class Visual implements IVisual {

    private tooltipService: tooltip.ITooltipServiceWrapper;

    constructor(options: VisualConstructorOptions) {
        this.tooltipService = tooltooltip.createTooltipServiceWrapper(
            options.host.tooltipService,
            options.element);
    }
}

addTooltip

この関数は引数に渡した d3 セレクションに対してツールティップを追加。また mouseover の挙動も内部的に追加されるため別途コードは不要。

addTooltip<T>(selection: d3.Selection<any>, getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[], getDataPointIdentity?: (args: TooltipEventArgs<T>) => ISelectionId, reloadTooltipDataOnMouseMove?: boolean): void;

addTooltip の例

以下の例では、作成した tooltipService を使って、barContainer に含まれるすべての bar クラスが設定された要素に対して、バインドされているデータの Tooltips プロパティを表示するように設定。

import tooltip = powerbi.extensibility.utils.tooltip;
...

interface BarChartDataPoint {
        selectionId: ISelectionId;
        value: number;
        category: string;
        series: string;
        highlighted: boolean;
        color: string;
        tooltips: VisualTooltipDataItem[]
    };
...

public update(options: VisualUpdateOptions) {
    this.barContainer
        .selectAll('.bar')
        .call((d) => {
            this.tooltipService.addTooltip(
                d,
                (args: tooltip.TooltipEventArgs<BarChartDataPoint>) => {
                    return args.data.tooltips
                },
                (args: tooltip.TooltipEventArgs<BarChartDataPoint>) => {
                    return args.data.selectionId
                },
                true);
        }
    );

まとめ

使いやすいチャートにツールティップは欠かせません。是非追加してみてください。

参照

Tooltips in Custom Visuals
TooltipUtils
Installation Guide
Usage Guide