將工具提示新增至您的 Power BI 視覺效果

工具提示很適合用來為圖像上的資料點提供更多相關資訊和詳細資料。 Power BI 工具提示 API 可以處理下列互動：

• 顯示工具提示。
• 隱藏工具提示。
• 移動工具提示。

工具提示可以在指定的座標位置顯示一個具有標題、特定色彩值及其不透明度的文字元素。 此資料會提供給 API，而 Power BI 主機呈現它的方式，會與其呈現原生視覺效果之工具提示的方式相同。

您可以啟用新式工具提示功能來變更工具提示的樣式或新增切入動作。

下圖顯示範例橫條圖中的工具提示：

上面的工具提示影像說明單一橫條的類別和值。 您可以擴充工具提示以顯示多個值。

管理工具提示

您可以透過 ITooltipService 介面來管理視覺效果中的工具提示。 ITooltipService 會通知主機需要顯示、移除或移動工具提示。

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

您的視覺效果應偵測視覺效果內的滑鼠事件，並視需要呼叫 show()、move() 和 hide() 委派，並在工具提示 options 物件中填入適當的內容。 TooltipShowOptions 和 TooltipHideOptions 會依次定義要顯示的內容，以及在這些事件中的運作方式。

呼叫這些方法會牽涉到使用者事件 (例如滑鼠移動或觸控事件)，所以最好為這些事件建立接聽程式，進而叫用 TooltipService 成員。 下列範例會在名為 TooltipServiceWrapper 的類別中彙總。

TooltipServiceWrapper 類別

此類別背後的基本概念是持有 TooltipService 的實例，在相關元素上監聽 D3 滑鼠事件，然後在需要時調用 show() 和 hide() 元素。

類別會保存及管理這些事件的任何相關狀態和邏輯，它們主要是用於與基礎 D3 程式碼互動。 D3 互動和轉換已超出本文的範圍。

本文中的範例程式碼是以 SampleBarChart 視覺效果為基礎。 您可以在 barChart.ts 中檢查原始程式碼。

建立 TooltipServiceWrapper

橫條圖建構函式現在有 TooltipServiceWrapper 成員，它會在建構函式中搭配主機 tooltipService 執行個體進行具現化。

        private tooltipServiceWrapper: ITooltipServiceWrapper;

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

TooltipServiceWrapper 類別會保存 tooltipService 實例，也會作為視覺效果和觸控參數的根 D3 元素。

    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 方法是這個類別用來註冊事件接聽程式的單一進入點。

addTooltip 方法

        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<Element>：處理工具提示的 d3 元素。
• getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[]：用於填入每個上下文的工具提示內容 (顯示內容) 的委派。
• getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId：用於擷取資料點 ID 的委派 (在此範例中未使用)。
• reloadTooltipDataOnMouseMove? boolean：指出是否要在 MouseMove 事件 (未在此範例中使用) 期間重新整理工具提示資料的布林值。

如您所見，如果已停用 addTooltip 或沒有真正的選取項目，tooltipService 便會結束而不採取任何動作。

使用 show 方法以顯示工具提示

addTooltip 方法接著會接聽 D3 mouseover 事件，如下列程式碼所示：

        ...
        ...
        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。 它也會計算座標。
• getTooltipInfoDelegate：它接著會從 tooltipEventArgs 建置工具提示內容。 它是對 BarChart 類別的回呼，因為它是視覺效果的邏輯。 它是要在工具提示中顯示的實際文字內容。
• getDataPointIdentity：此範例中未使用。
• this.visualHostTooltipService.show：顯示工具提示的呼叫。

您可以在 mouseout 和 mousemove 事件的範例中找到其他處理。

如需詳細資訊，請參閱 SampleBarChart 視覺效果存放庫。

透過 getTooltipData 方法填入工具提示內容

BarChart 類別已搭配 getTooltipData 成員新增，該成員只會將資料點的 category、value 和 color 擷取至 VisualTooltipDataItem[] 元素。

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

在上述實作中，header 成員是常數，但您可將它用於需要動態值的更複雜實作。 您可以填入多個元素至 VisualTooltipDataItem[]，使工具提示包含多行。 這在如堆疊橫條圖的視覺效果中很有用，其中工具提示可能會顯示來自多個資料點的資料。

呼叫 addTooltip 方法

最後一步是在實際資料可能發生變動時呼叫 addTooltip。 這個呼叫會在 BarChart.update() 方法中進行。 會進行呼叫來監視所有 "bar" 元素的選取項目，只傳遞 BarChart.getTooltipData()(如上所述)。

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

將工具提示支援新增至報表頁面

若要新增報表頁面工具提示支援 (能夠在報表頁面的格式窗格中修改工具提示)，請在 tooltips 檔案中新增 物件。

例如：

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

然後，您可以從報表頁面的格式化窗格中定義工具提示。

• supportedTypes：此視覺化所支援的工具提示設定，會在欄位中得到良好的反映。
  • default：指定是否支援透過資料欄位的「自動」工具提示繫結。
  • canvas：指定是否支援報表頁面工具提示。
• roles：(選擇性) 定義之後，會指示有哪些資料角色會繫結至欄位中選取的工具提示選項。

如需詳細資訊，請參閱報表頁面工具提示使用指導方針 \(英文\)。

為了顯示報表頁面工具提示，在 Power BI 主機呼叫 ITooltipService.Show(options: TooltipShowOptions) 或 ITooltipService.Move(options: TooltipMoveOptions) 之後，它會使用 selectionId (前面 identities 引數的 options 屬性)。 若要讓工具提示擷取，SelectionId 應該代表您將游標暫留在其上之項目的選取資料 (類別、數列等)。

下列程式碼會顯示將 selectionId 傳送至工具提示顯示呼叫的範例：

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

將現代的工具提示支援新增至報表頁面

從 API 3.8.3 版起，您還可以建立新式 視覺效果工具提示。 新式可視化工具提示會將資料點切入動作新增至您的工具提示中，並更新樣式來符合您的報表佈景主題。 若要了解您正在使用哪個版本，請檢查 apiVersion 檔案中的 。

若要管理報表頁面新式工具提示支援，請將 supportEnhancedTooltips 屬性新增至 tooltips 檔案中的 物件。

例如：

{
    "tooltips": {
        ... ,
        "supportEnhancedTooltips": true
    }
}

請參閱 SampleBarChart 程式碼中使用的新式工具提示功能的範例。

注意

將此功能新增至 capabilities.json 檔案中，可讓使用者能夠為報表啟用此功能。

相關內容

• 工具提示公用程式
• Power BI 視覺化提示
• 在 Power BI Desktop 中根據報表頁面建立工具提示