分享方式：

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

  • 文章

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

如需書籤的詳細資訊，請參閱在 Power BI 中使用書籤來共用深入解析並建立故事 \(部分機器翻譯\)。

支援書籤的視覺效果

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

注意

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

  • 針對使用 SelectionManager 的非篩選視覺效果，Visual API 1.11.0 版或更新版本。
  • 適用於篩選視覺效果的 Visual API 2.6.0 版或更新版本。
  • 若要了解您正在使用哪個版本，請檢查 pbiviz.json 檔案中的 apiVersion。

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

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

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

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

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

新的選取項目狀態 (或篩選條件) 會透過 update 方法中的 options.jsonFilters 屬性來傳達。 jsonFilters 可以是 Advanced Filter 或 Tuple Filter。

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

含有選取項目的視覺效果

注意

InteractivityService 已被取代。

如果您的視覺效果使用選取項目 \(英文\) 與其他視覺效果互動，您可以透過下列兩種方式之一來新增書籤支援：

使用 InteractivityService 還原書籤選取項目 - 已淘汰

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

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

使用 SelectionManager 還原書籤選取項目

您可以使用 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 物件中的目前選取項目狀態。 然後，在呈現資料點時，自訂視覺效果的選取項目狀態會符合書籤的狀態。

含有篩選的視覺效果

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

視覺效果會建立一個進階篩選並呼叫主機方法 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
}

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

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

儲存視覺效果的篩選狀態

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

例如，時間軸交叉分析篩選器會將 Granularity 屬性值儲存在篩選狀態中。 它可讓您在變更書籤時變更時間軸 (天、月、年等) 的細微性。

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

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

相關內容