Power BI ビジュアルのヒントTooltips in Power BI visuals

ビジュアルで Power BI のヒントのサポートを利用できるようになりました。Visuals can now make use of Power BI tooltip support. Power BI のヒントでは、次の操作が処理されます。Power BI tooltips handle the following interactions:

  • ヒントを表示する。Show a tooltip.
  • ヒントを非表示にする。Hide a tooltip.
  • ヒントを移動する。Move a tooltip.

ヒントには、タイトル、特定の色の値、指定された座標セットの不透明度を含むテキスト要素を表示できます。Tooltips can display a textual element with a title, a value in a given color, and opacity at a specified set of coordinates. このデータは API に提供され、Power BI ホストでは、ネイティブ ビジュアルのヒントがレンダリングされるのと同じ方法でそれがレンダリングされます。This data is provided to the API, and the Power BI host renders it the same way it renders tooltips for native visuals.

次の画像は、サンプルの棒グラフのヒントを示しています。A tooltip in a sample bar chart is shown in the following image:

サンプルの棒グラフのヒント

前のヒントの画像は、1 つのバー カテゴリと値を示しています。The preceding tooltip image illustrates a single bar category and value. 1 つのヒントを拡張して、複数の値を表示できます。You can extend a single tooltip to display multiple values.

ヒントの管理Manage tooltips

ヒントの管理に使用するインターフェイスは、"ITooltipService" です。The interface through which you manage tooltips is the "ITooltipService." これは、ヒントを表示、削除、または移動する必要があることをホストに通知するために使用されます。It's used to notify the host that a tooltip needs to be displayed, removed, or moved.

    interface ITooltipService {
        enabled(): boolean;
        show(options: TooltipShowOptions): void;
        move(options: TooltipMoveOptions): void;
        hide(options: TooltipHideOptions): void;
    }

ご利用のビジュアルでは、ビジュアル内のマウス イベントをリッスンし、Tooltip****Options オブジェクトに設定されている適切なコンテンツで必要に応じて、show()move()hide() の委任を呼び出す必要があります。Your visual needs to listen to the mouse events within your visual and call the show(), move(), and hide() delegates, as needed, with the appropriate content populated in the Tooltip****Options objects. その後、TooltipShowOptionsTooltipHideOptions で、表示内容とこれらのイベントでの動作方法が定義されます。TooltipShowOptions and TooltipHideOptions would in turn define what to display and how to behave in these events.

これらのメソッドを呼び出すと、マウスの移動やタッチ イベントなどのユーザー イベントが発生するため、これらのイベントのリスナーを作成することをお勧めします。これにより、TooltipService メンバーが呼び出されます。Because calling these methods involves user events such as mouse moves and touch events, it's a good idea to create listeners for these events, which would in turn invoke the TooltipService members. このサンプルでは、TooltipServiceWrapper というクラスで集計を行います。Our sample aggregates in a class called TooltipServiceWrapper.

TooltipServiceWrapper クラスThe TooltipServiceWrapper class

このクラスの背後にある基本的な考え方は、TooltipService のインスタンスを保持し、関連する要素に対する D3 マウス イベントをリッスンしてから、show()hide() を呼び出し、必要に応じて要素を呼び出すことです。The basic idea behind this class is to hold the instance of the TooltipService, listen to D3 mouse events over relevant elements, and then make the calls to show() and hide() the elements when needed.

クラスでは、これらのイベントに関連するすべての状態とロジックが保持および管理されます。ほとんどの場合、これは基になる D3 コードとのインターフェイスが対象となります。The class holds and manages any relevant state and logic for these events, which are mostly geared at interfacing with the underlying D3 code. D3 インターフェイスと変換は、この記事の範囲外です。The D3 interfacing and conversion is out of scope for this article.

完全なサンプル コードについては、SampleBarChart ビジュアル リポジトリで見つけることができます。You can find the full sample code in SampleBarChart visual repository.

TooltipServiceWrapper の作成Create TooltipServiceWrapper

横棒グラフのコンストラクターに TooltipServiceWrapper メンバーが含まれるようになりました。これは、ホスト tooltipService インスタンスと共にコンストラクターでインスタンス化されます。The bar chart constructor now has a TooltipServiceWrapper member, which is instantiated in the constructor with the host tooltipService instance.

        private tooltipServiceWrapper: ITooltipServiceWrapper;

        this.tooltipServiceWrapper = createTooltipServiceWrapper(this.host.tooltipService, options.element);

TooltipServiceWrapper クラスでは、tooltipService インスタンスが、ビジュアルおよびタッチ パラメーターのルート D3 要素としても保持されます。The TooltipServiceWrapper class holds the tooltipService instance, also as the root D3 element of the visual and touch parameters.

    class TooltipServiceWrapper implements ITooltipServiceWrapper {
        private handleTouchTimeoutId: number;
        private visualHostTooltipService: ITooltipService;
        private rootElement: Element;
        private handleTouchDelay: number;

        constructor(tooltipService: ITooltipService, rootElement: Element, handleTouchDelay: number) {
            this.visualHostTooltipService = tooltipService;
            this.handleTouchDelay = handleTouchDelay;
            this.rootElement = rootElement;
        }
        .
        .
        .
    }

このクラスでイベント リスナーを登録するための単一のエントリ ポイントは、addTooltip メソッドです。The single entry point for this class to register event listeners is the addTooltip method.

addTooltip メソッドThe addTooltip method

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

            if (!selection || !this.visualHostTooltipService.enabled()) {
                return;
            }
        ...
        ...
        }
  • selection: d3.Selection : ヒントが処理される d3 要素。selection: d3.Selection: The d3 elements over which tooltips are handled.

  • getTooltipInfoDelegate: (args:TooltipEventArgs) => VisualTooltipDataItem[] : コンテキストごとにヒント コンテンツ (表示内容) を作成するための委任。getTooltipInfoDelegate: (args: TooltipEventArgs) => VisualTooltipDataItem[]: The delegate for populating the tooltip content (what to display) per context.

  • getDataPointIdentity: (args:TooltipEventArgs) => ISelectionId: データ ポイント ID を取得するための委任 (このサンプルでは使用されません)。getDataPointIdentity: (args: TooltipEventArgs) => ISelectionId: The delegate for retrieving the data point ID (unused in this sample).

  • reloadTooltipDataOnMouseMove? boolean: MouseMove イベント中にヒント データを更新するかどうかを示すブール値 (このサンプルでは使用されません)。reloadTooltipDataOnMouseMove? boolean: A Boolean that indicates whether to refresh the tooltip data during a MouseMove event (unused in this sample).

ご覧のとおり、tooltipService が無効になっている場合や、実際の選択がない場合は、アクションなしで addTooltip が終了します。As you can see, addTooltip exits with no action if the tooltipService is disabled or there's no real selection.

ヒントを表示するための show メソッドを呼び出すCall the show method to display a tooltip

次のコードに示すように、addTooltip メソッドでは次に D3 の mouseover イベントをリッスンします。The addTooltip method next listens to the D3 mouseover event, as shown in the following code:

        ...
        ...
        selection.on("mouseover.tooltip", () => {
            // Ignore mouseover while handling touch events
            if (!this.canDisplayTooltip(d3.event))
                return;

            let tooltipEventArgs = this.makeTooltipEventArgs<T>(rootNode, true, false);
            if (!tooltipEventArgs)
                return;

            let tooltipInfo = getTooltipInfoDelegate(tooltipEventArgs);
            if (tooltipInfo == null)
                return;

            let selectionId = getDataPointIdentity(tooltipEventArgs);

            this.visualHostTooltipService.show({
                coordinates: tooltipEventArgs.coordinates,
                isTouchEvent: false,
                dataItems: tooltipInfo,
                identities: selectionId ? [selectionId] : [],
            });
        });
  • makeTooltipEventArgs: D3 で選択された要素から tooltipEventArgs にコンテキストが抽出されます。makeTooltipEventArgs: Extracts the context from the D3 selected elements into a tooltipEventArgs. これにより、座標も計算されます。It calculates the coordinates as well.

  • getTooltipInfoDelegate: その後、tooltipEventArgs からヒント コンテンツが構築されます。getTooltipInfoDelegate: It then builds the tooltip content from the tooltipEventArgs. これはビジュアルのロジックであるため、BarChart クラスへのコールバックです。It's a callback to the BarChart class, because it is the visual's logic. これは、ヒントに表示される実際のテキスト コンテンツです。It's the actual text content to display in the tooltip.

  • getDataPointIdentity: このサンプルでは使用されません。getDataPointIdentity: Unused in this sample.

  • this.visualHostTooltipService.show: ヒントを表示するための呼び出し。this.visualHostTooltipService.show: The call to display the tooltip.

追加の処理については、mouseout および mousemove イベントのサンプルを参照してください。Additional handling can be found in the sample for mouseout and mousemove events.

詳細については、SampleBarChart ビジュアル リポジトリに関するページを参照してください。For more information, see the SampleBarChart visual repository.

getTooltipData メソッドによるヒント コンテンツの設定Populate the tooltip content by the getTooltipData method

BarChart クラスは、データ ポイントの categoryvaluecolor を VisualTooltipDataItem[] 要素に抽出するだけの getTooltipData メンバーと共に追加されました。The BarChart class was added with a getTooltipData member, which simply extracts the category, value, and color of the data point into a VisualTooltipDataItem[] element.

        private static getTooltipData(value: any): VisualTooltipDataItem[] {
            return [{
                displayName: value.category,
                value: value.value.toString(),
                color: value.color,
                header: 'ToolTip Title'
            }];
        }

前の実装では、header メンバーは定数ですが、動的な値を必要とする、より複雑な実装にこれを使用できます。In the preceding implementation, the header member is constant, but you can use it for more complex implementations, which require dynamic values. VisualTooltipDataItem[] には複数の要素を設定できます。これにより、複数の行がヒントに追加されます。You can populate the VisualTooltipDataItem[] with more than one element, which adds multiple lines to the tooltip. これは、ヒントに複数のデータ ポイントのデータが表示される可能性のある積み上げ横棒グラフなどのビジュアルで役に立つ場合があります。It can be useful in visuals such as stacked bar charts where the tooltip may display data from more than a single data point.

addTooltip メソッドを呼び出すCall the addTooltip method

最後の手順では、実際のデータが変更される可能性がある場合に addTooltip メソッドを呼び出します。The final step is to call the addTooltip method when the actual data might change. この呼び出しは BarChart.update() メソッドで行われます。This call takes place in the BarChart.update() method. 前述のとおり、BarChart.getTooltipData() のみを渡すことで、すべての 'bar' 要素の選択を監視するために呼び出しが行われます。A call is made to monitor the selection of all the 'bar' elements, passing only the BarChart.getTooltipData(), as mentioned previously.

        this.tooltipServiceWrapper.addTooltip(this.barContainer.selectAll('.bar'),
            (tooltipEvent: TooltipEventArgs<number>) => BarChart.getTooltipData(tooltipEvent.data),
            (tooltipEvent: TooltipEventArgs<number>) => null);

レポート ページのヒントを追加するAdd report page tooltips

レポート ページのヒントのサポートを追加するために、ほとんどの変更を capabilities.json ファイルで見つけることができます。To add report page tooltips support, you'll find most changes in the capabilities.json file.

サンプル スキーマは次のとおりです。A sample schema is

{
    "tooltips": {
        "supportedTypes": {
            "default": true,
            "canvas": true
        },
        "roles": [
            "tooltips"
        ]
    }
}

書式ウィンドウでは、レポート ページのヒントを定義できます。You can define report page tooltips in the Format pane.

レポート ページのヒント

  • supportedTypes:ビジュアルでサポートされるヒントの構成であり、フィールドでも反映されます。supportedTypes: The tooltip configuration that's supported by the visual and reflected in the fields well.

    • default:データ フィールドを介した "自動" ヒント バインドがサポートされるかどうかを示します。default: Specifies whether the "automatic" tooltips binding via the data field is supported.
    • canvas:レポート ページのヒントがサポートされるかどうかを示します。canvas: Specifies whether the report page tooltips are supported.
  • roles:(省略可能) 定義された後、フィールドでも選択されたヒント オプションにバインドされるデータ ロールが指示されます。roles: (Optional) After it's defined, it instructs what data roles are bound to the selected tooltip option in the fields well.

詳細については、レポート ページのヒントの使用に関するガイドラインを参照してください。For more information, see Report page tooltips usage guidelines.

レポート ページのヒントを表示するには、Power BI ホストで ITooltipService.Show(options: TooltipShowOptions) または ITooltipService.Move(options: TooltipMoveOptions) を呼び出した後、selectionId (前の options 引数の identities プロパティ) が使用されます。To display the report page tooltip, after the Power BI host calls ITooltipService.Show(options: TooltipShowOptions) or ITooltipService.Move(options: TooltipMoveOptions), it consumes the selectionId (identities property of the preceding options argument). ヒントによって取得されるように、SelectionId では、マウスでポイントした項目の選択されたデータ (カテゴリや系列など) を表す必要があります。To be retrieved by the tooltip, SelectionId should represent the selected data (category, series, and so on) of the item you hovered over.

次のコードでは、selectionId を送信してヒントを表示するための呼び出し例を示しています。An example of sending the selectionId to tooltip display calls is shown in the following code:

    this.tooltipServiceWrapper.addTooltip(this.barContainer.selectAll('.bar'),
        (tooltipEvent: TooltipEventArgs<number>) => BarChart.getTooltipData(tooltipEvent.data),
        (tooltipEvent: TooltipEventArgs<number>) => tooltipEvent.data.selectionID);