ツールヒント ユーティリティ

  • [アーティクル]

この記事では、ツールヒント ユーティリティのインストール、インポート、使用について説明します。 このユーティリティは、Power BI 視覚化のツールヒントをカスタマイズするのに役立ちます。

要件

パッケージを使用するには、次のものが必要です。

  • node.js (最新の LTS バージョンをお勧めします)
  • npm (サポートされる最小バージョンは 3.0.0 です)
  • PowerBI-visuals-tools によって作成されたカスタム ビジュアル

インストール

パッケージをインストールするには、現在のビジュアルを使用して、ディレクトリ内で次のコマンドを実行する必要があります。

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

このコマンドを実行すると、パッケージがインストールされ、パッケージが依存関係として package.json ファイルに追加されます。

使用法

使用ガイドでは、パッケージのパブリック API について説明されています。 パッケージの各パブリック インターフェイスについて、説明といくつかの例が提供されています。

このパッケージには、ツールヒント アクションを処理するための TooltipServiceWrapper とメソッドを作成するための方法が用意されています。 ツールヒント インターフェイス ITooltipServiceWrapper、TooltipEventArgs、TooltipEnabledDataPoint を使用します。

モバイル開発に関連する特定のメソッド (タッチ イベント ハンドラー) があります (touchEndEventName、touchStartEventName、usePointerEvents)。

TooltipServiceWrapper により、ツールヒントを操作するための最も簡単な方法が提供されます。

このモジュールでは、次のインターフェイスと関数が提供されます。

createTooltipServiceWrapper

この関数により、ITooltipServiceWrapper のインスタンスを作成できます。

function createTooltipServiceWrapper(tooltipService: ITooltipService, rootElement: Element, handleTouchDelay?: number,  getEventMethod?: () => MouseEvent): ITooltipServiceWrapper;

ITooltipService は IVisualHost で使用できます。

例:

import { createTooltipServiceWrapper } from "powerbi-visuals-utils-tooltiputils";

export class YourVisual implements IVisual {
    // implementation of IVisual.

    constructor(options: VisualConstructorOptions) {
        createTooltipServiceWrapper(
            options.host.tooltipService,
            options.element);

        // returns: an instance of ITooltipServiceWrapper.
    }
}

カスタム視覚化の例については、こちらを参照してください。

ITooltipServiceWrapper

このインターフェイスでは、TooltipService のパブリック メソッドが記述されています。

interface ITooltipServiceWrapper {
    addTooltip<T>(selection: d3.Selection<any, any, any, any>, getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => powerbi.extensibility.VisualTooltipDataItem[], getDataPointIdentity?: (args: TooltipEventArgs<T>) => powerbi.visuals.ISelectionId, reloadTooltipDataOnMouseMove?: boolean): void;
    hide(): void;
}

ITooltipServiceWrapper.addTooltip

このメソッドでは、現在の選択範囲にツールヒントが追加されます。

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

例:

import { createTooltipServiceWrapper, TooltipEventArgs, ITooltipServiceWrapper, TooltipEnabledDataPoint } from "powerbi-visuals-utils-tooltiputils";

let bodyElement = d3.select("body");

let element = bodyElement
    .append("div")
    .style({
        "background-color": "green",
        "width": "150px",
        "height": "150px"
    })
    .classed("visual", true)
    .data([{
        tooltipInfo: [{
            displayName: "Power BI",
            value: 2016
        }]
    }]);

let tooltipServiceWrapper: ITooltipServiceWrapper = createTooltipServiceWrapper(tooltipService, bodyElement.get(0)); // tooltipService is from the IVisualHost.

tooltipServiceWrapper.addTooltip<TooltipEnabledDataPoint>(element, (eventArgs: TooltipEventArgs<TooltipEnabledDataPoint>) => {
    return eventArgs.data.tooltipInfo;
});

// You will see a tooltip if you mouseover the element.

カスタム視覚化の例については、こちらを参照してください。

ガント カスタム視覚化のツールヒントのカスタマイズ例については、こちらを参照してください。

ITooltipServiceWrapper.hide

このメソッドでは、ツールヒントが非表示にされます。

hide(): void;

例:

import {createTooltipServiceWrapper} from "powerbi-visuals-utils-tooltiputils";

let tooltipServiceWrapper = createTooltipServiceWrapper(options.host.tooltipService, options.element); // options are from the VisualConstructorOptions.

tooltipServiceWrapper.hide();

Interfaces

インターフェイスは、TooltipServiceWrapper の作成時と使用時に使用されます。 それらは、こちらの前の記事の例に記載されています。

TooltipEventArgs

interface TooltipEventArgs<TData> {
    data: TData;
    coordinates: number[];
    elementCoordinates: number[];
    context: HTMLElement;
    isTouchEvent: boolean;
}

TooltipEnabledDataPoint

interface TooltipEnabledDataPoint {
    tooltipInfo?: powerbi.extensibility.VisualTooltipDataItem[];
}

TooltipServiceWrapperOptions

interface TooltipServiceWrapperOptions {
    tooltipService: ITooltipService;
    rootElement: Element;
    handleTouchDelay: number;

Touch events

ツールヒント ユーティリティでは、モバイル開発に役立ついくつかのタッチ イベントを処理できるようになりました。

touchStartEventName

function touchStartEventName(): string

このメソッドでは、タッチ開始イベント名が返されます。

touchEndEventName

function touchEndEventName(): string

このメソッドでは、タッチ終了イベント名が返されます。

usePointerEvents

function usePointerEvents(): boolean

このメソッドでは、ポインターに関連する、または関連しない、現在の touchStart イベントが返されます。