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

# TooltipUtils

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

# インストール

以下手順で追加。

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

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

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

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

3\. pbiviz.json の externalJS に追加。

```json:pbiviz.json
{
  ...
  "externalJS": [
    ...,
    "node_modules/powerbi-visuals-utils-tooltiputils/lib/index.js"
  ],
  ...
}
```
# 機能

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

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

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

- [createTooltipServiceWrapper](#createtooltipservicewrapper)
- [addTooltip](#itooltipservicewrapperaddtooltip)

## createTooltipServiceWrapper

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

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

### createTooltipServiceWrapper の例

```typescript
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 の挙動も内部的に追加されるため別途コードは不要。

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

### addTooltip の例

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

```typescript

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);
        }
    );
```

![image.png](https://qiita-image-store.s3.amazonaws.com/0/214116/9970dbf7-e017-d44a-e2d2-279228289038.png)

# まとめ

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

# 参照

[Tooltips in Custom Visuals](https://github.com/Microsoft/PowerBI-visuals/blob/master/Visual/Tooltips.md#tooltipservicewrapper)
[TooltipUtils](https://github.com/Microsoft/powerbi-visuals-utils-tooltiputils)
[Installation Guide](./docs/usage/installation-guide.md)
[Usage Guide](./docs/usage/usage-guide.md)