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

この記事では、ツールヒント ユーティリティのインストール、インポート、使用について説明します。This article will help you to install, import, and use tooltip utils. このユーティリティは、Power BI ビジュアルのツールヒントをカスタマイズするのに役立ちます。This util useful for any tooltip customization in Power BI visuals.

要件Requirements

パッケージを使用するには、次のものが必要です。To use the package, you should have the following things:

  • node.js (最新の LTS バージョンをお勧めします)node.js (we recommend the latest LTS version)
  • npm (サポートされる最小バージョンは 3.0.0 です)npm (the minimal supported version is 3.0.0)
  • PowerBI-visuals-tools で作成されたカスタム ビジュアルThe custom visual created by PowerBI-visuals-tools

インストールInstallation

パッケージをインストールするには、現在のビジュアルを使用して、ディレクトリ内で次のコマンドを実行する必要があります。To install the package, you should run the following command in the directory with your current visual:

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

このコマンドを実行すると、パッケージがインストールされ、依存関係としてパッケージが package.json に追加されますThis command installs the package and adds a package as a dependency to your package.json

使用法Usage

使用ガイドでは、パッケージのパブリック API について説明されています。The Usage Guide describes a public API of the package. パッケージの各パブリック インターフェイスについての説明といくつかの例が提供されています。You will find a description and a few examples for each public interface of the package.

このパッケージには、ツールヒント アクションを処理するための TooltipServiceWrapper とメソッドを作成するための方法が用意されています。This package contains provide you the way to create TooltipServiceWrapper and methods to help handle tooltip actions. ツールヒント インターフェイス ITooltipServiceWrapperTooltipEventArgsTooltipEnabledDataPoint を使用します。It uses tooltip interfaces - ITooltipServiceWrapper, TooltipEventArgs, TooltipEnabledDataPoint.

また、モバイル開発に関連する特定のメソッド (タッチ イベント ハンドラー) もあります (touchEndEventNametouchStartEventNameusePointerEvents)。Also it has specific methods (touch events handlers) related to mobile development: touchEndEventName, touchStartEventName, usePointerEvents.

TooltipServiceWrapper では、ツールヒントを操作するための最も簡単な方法が提供されています。TooltipServiceWrapper provides the simplest way in order to manipulate tooltips.

このモジュールでは、次のインターフェイスと関数が提供されます。This module provides the following interface and function:

createTooltipServiceWrapper

この関数では、ITooltipServiceWrapper のインスタンスが作成されます。This function creates an instance of ITooltipServiceWrapper.

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

ITooltipServiceIVisualHost で使用できます。The ITooltipService is available in IVisualHost.

Example

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.
    }
}

カスタム ビジュアルのコード例については、こちらを参照してください。You can take a look at the example code of the custom visual here.

ITooltipServiceWrapper

このインターフェイスでは、TooltipService のパブリック メソッドが記述されています。This interface describes public methods of the 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

このメソッドでは、現在の選択範囲にツールヒントが追加されます。This method adds tooltips to the current selection.

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

Example

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.

カスタム ビジュアルのコード例については、こちらを参照してください。You can take a look at the example code of the custom visual here.

また、ガント カスタム ビジュアルでのツールヒントのカスタマイズに関するこちらの例に注意してくださいAlso pay attention at following example of tooltip customization in Gantt custom visual here

ITooltipServiceWrapper.hide

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

hide(): void;

Example

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

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

tooltipServiceWrapper.hide();

Interfaces

このインターフェイスは、TooltipServiceWrapper を作成して使用するときに使用されます。This interfaces are used during TooltipServiceWrapper creation and it's usage. また、前のトピックの例でも説明されています。Also they were mentioned in examples from previous topic here.

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;
    getEventMethod?: () => MouseEvent;

Touch events

ツールヒント ユーティリティでは、複数のタッチ イベントを処理できるようになりました。これはモバイル開発に役ちます。Now tooltip utils has ability to handle several touch events useful for mobile development.

touchStartEventName

function touchStartEventName(): string

このメソッドでは、タッチ開始イベント名が返されます。This method returns touch start event name.

touchEndEventName

function touchEndEventName(): string

このメソッドでは、タッチ開始イベント名が返されます。This method returns touch start event name.

usePointerEvents

function usePointerEvents(): boolean

このメソッドでは、ポインターに関連する、または関連しない、現在の touchStart イベントが返されます。This method returns is current touchStart event related to pointer or not.