共用方式為

工具提示公用程式

  • 發行項

此文章將協助您安裝、匯入及使用工具提示公用程式。 此公用程式適用於 Power BI 視覺效果中的工具提示自訂。

必要條件

若要使用套件，您需要：

安裝

若要安裝套件，您應該在具有目前視覺效果的目錄中執行下列命令：

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;

您可以在 IVisualHost 中找到 ITooltipService。

範例：

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 事件是否與指標相關。