共用方式為

將書籤支援新增至Power BI報表中的視覺效果

  • 發行項

使用 Power BI 報表書籤，您可以擷取和儲存報表頁面的已設定檢視。 然後，您可以隨時隨地快速且輕鬆地返回儲存的檢視。 書籤會儲存整個組態，包括選取項目和篩選。

如需書籤的詳細資訊，請參閱 在Power BI中使用書籤來共用深入解析和建置劇本。

支援書籤的視覺效果

支援書籤的Power BI視覺效果必須能夠在需要時儲存並提供正確的資訊。 如果您的視覺效果與其他視覺效果互動，請選取數據點或篩選其他視覺效果，您必須將書籤狀態儲存在視覺效果的 filterState 屬性中。

注意

建立支援書籤的視覺效果需要：

  • Powerbi-visuals-utils-interactivityutils 3.0.0 版或更新版本，用於篩選視覺效果，以及使用 InteractivityService的任何視覺效果。
  • 針對使用 SelectionManager 而非 InteractivityService的非篩選視覺效果，Visual API 1.11.0 版或更新版本。
  • 若要找出您使用的版本，請在 pbiviz.json 檔案中籤apiVersion入 。

Power BI 視覺效果如何在報表書籤中與 Power BI 互動

假設您想要在報表頁面上建立數個書籤，且每個書籤都已選取不同的數據點。

首先，選取視覺效果中的一或多個數據點。 視覺效果會將您的選取項目傳遞至主機。 然後選取 [書籤] 窗格中的 [新增]。 Power BI 會儲存新書籤的目前選取範圍。

執行此動作數次以建立新的書籤。 建立書籤之後，您可以在書籤之間切換。

每次選取書籤時，Power BI 都會還原儲存的篩選或選取狀態，並將它傳遞給視覺效果。 報表中的視覺效果會根據儲存在書籤中的狀態醒目提示或篩選。 若要還原正確的狀態，您的視覺效果必須將正確的選取狀態傳遞至主機（例如轉譯數據點的色彩）。

新的選取狀態（或篩選條件）會透過 options.jsonFilters 方法中的 update 屬性進行通訊。 jsonFilters可以是 Advanced Filter 或 Tuple Filter。

  • 如果您的視覺效果包含選取的數據點，請使用 中的ISelectionManager回呼函式 ，registerOnSelectCallback將選取範圍重設為選取的書籤。
  • 如果您的視覺效果使用篩選來選取數據， 請將篩選 值重設為所選書籤的對應值。

具有選取範圍的視覺效果

如果您的視覺效果使用 Selection 與其他視覺效果互動，您可以使用下列兩種方式之一新增書籤支援：

  • 透過 InteractivityService 來管理選取專案，請使用 applySelectionFromFilter。 這是較簡單且慣用的方法。
  • 如果您的視覺效果不使用互動服務，請透過 SelectionManager。

使用 InteractivityService 還原書籤選取專案

如果您的視覺效果使用 InteractivityService，則不需要任何其他動作來支持視覺效果中的書籤。

當您選取書籤時，公用程式會自動處理視覺效果的選取狀態。

使用 SelectionManager 還原書籤選取專案

如果您未使用 InteractivityService，您可以使用 方法儲存並重新叫用 ISelectionManager.registerOnSelectCallback 書籤選取專案，如下所示：

當您選取書籤時，Power BI 會使用對應的選取專案呼叫 callback 視覺效果的 方法。

this.selectionManager.registerOnSelectCallback(
    (ids: ISelectionId[]) => {
        //called when a selection was set by Power BI
    });
);

假設您在視覺效果的 visualTransform 方法中建立了數據點。

datapoints看起來像這樣：

visualDataPoints.push({
    category: categorical.categories[0].values[i],
    color: getCategoricalObjectValue<Fill>(categorical.categories[0], i, 'colorSelector', 'fill', defaultColor).solid.color,
    selectionId: host.createSelectionIdBuilder()
        .withCategory(categorical.categories[0], i)
        .createSelectionId(),
    selected: false
});

您現在擁有 visualDataPoints 作為數據點和 ids 傳遞至函式的 callback 數位。

此時，視覺效果應該比較 ISelectionId[] 陣列與陣列中的 visualDataPoints 選取專案，然後將對應的數據點標示為選取。

this.selectionManager.registerOnSelectCallback(
    (ids: ISelectionId[]) => {
        visualDataPoints.forEach(dataPoint => {
            ids.forEach(bookmarkSelection => {
                if (bookmarkSelection.equals(dataPoint.selectionId)) {
                    dataPoint.selected = true;
                }
            });
        });
    });
);

更新數據點之後，它們會反映儲存在物件中的 filter 目前選取狀態。 然後，當轉譯數據點時，自定義視覺效果的選取狀態會符合書籤的狀態。

具有篩選的視覺效果

若要在具有篩選的視覺效果中支援書籤，請使用 InteractivityService。

假設視覺效果會依日期範圍建立數據的篩選。 您有 startDate 和 endDate 作為範圍的開始和結束日期。

視覺效果會建立進階篩選，並呼叫host方法來 applyJsonFilter 依相關條件篩選數據。

目標是用於篩選的數據表。

import { AdvancedFilter } from "powerbi-models";

const filter: IAdvancedFilter = new AdvancedFilter(
    target,
    "And",
    {
        operator: "GreaterThanOrEqual",
        value: startDate
            ? startDate.toJSON()
            : null
    },
    {
        operator: "LessThanOrEqual",
        value: endDate
            ? endDate.toJSON()
            : null
    });

this.host.applyJsonFilter(
    filter,
    "general",
    "filter",
    (startDate && endDate)
        ? FilterAction.merge
        : FilterAction.remove
);

每次您選取書籤時，自定義視覺效果都會取得 update 呼叫。

在 方法中 update ，視覺效果會檢查 物件中的篩選：

const filter: IAdvancedFilter = FilterManager.restoreFilter(
    && options.jsonFilters
    && options.jsonFilters[0] as any
) as IAdvancedFilter;

filter如果物件不是 Null，視覺效果會從 物件還原篩選條件：

const jsonFilters: AdvancedFilter = this.options.jsonFilters as AdvancedFilter[];

if (jsonFilters
    && jsonFilters[0]
    && jsonFilters[0].conditions
    && jsonFilters[0].conditions[0]
    && jsonFilters[0].conditions[1]
) {
    const startDate: Date = new Date(`${jsonFilters[0].conditions[0].value}`);
    const endDate: Date = new Date(`${jsonFilters[0].conditions[1].value}`);

    // apply restored conditions
} else {
    // apply default settings
}

之後，視覺效果會變更其內部狀態，以符合目前的條件。 內部狀態包括數據點和視覺效果物件（線條、矩形等等）。

重要

在上述報表書簽案例中，視覺效果不應該呼叫 applyJsonFilter 來篩選其他視覺效果。 Power BI 已篩選它們。

時間軸交叉分析篩選器視覺效果會將範圍選取器變更為對應的數據範圍。

儲存視覺效果的篩選狀態

除了儲存書籤篩選條件之外，您也可以儲存其他篩選層面。

例如，時間軸交叉分析篩選器會將Granularity屬性值儲存為篩選狀態。 它可讓您在變更書籤時變更時間軸（天、月、年等）的粒度。

屬性會將 filterState 篩選層面儲存為屬性。 視覺效果可以將各種 filterState 值儲存在書籤中。

若要將屬性值儲存為篩選狀態，請將物件屬性"filterState": true設定為 capabilities.json 檔案中的 。

相關內容

什麼是書籤

在桌面報表中建立書籤