向 Power BI 报表中的视觉对象添加书签支持

借助 Power BI 报表书签，可以捕获并保存报表页的配置视图。 然后，可以随时快速、轻松地返回保存的视图。 书签会保存整个配置，包括选择项和筛选器。

有关书签的详细信息，请参阅使用书签在 Power BI 中共享见解和创建故事。

支持书签的视觉对象

支持书签的 Power BI 视觉对象必须能够根据需要保存并提供正确的信息。 如果视觉对象与其他视觉对象交互、选择数据点或筛选其他视觉对象，则需要将已加入书签状态保存在视觉对象的 filterState 属性中。

备注

创建支持书签的视觉对象时需要：

• Powerbi-visuals-utils-interactivityutils 版本 3.0.0 或更高版本，用于筛选器视觉对象以及使用 InteractivityService 的任何视觉对象。

• 视觉对象 API 版本 1.11.0 或更高版本，用于使用 SelectionManager 而不是 InteractivityService 的非筛选器视觉对象。

Power BI 视觉对象如何在报表书签中与 Power BI 进行交互

假设你希望在报表页上创建多个书签，且每个书签都选择不同的数据点。

首先，在视觉对象中选择一个或多个数据点。 视觉对象将你的选择传递给主机。 然后在“书签”窗格中选择“添加”，Power BI 将保存新书签的当前选择 。

多次执行此操作以创建新书签。 创建书签后，可以在它们之间进行切换。

每次选择一个书签后，Power BI 会还原已保存的筛选器或选择状态并传递给视觉对象。 根据书签中存储的状态突出显示或筛选报表中的视觉对象。 为此，视觉对象必须将正确的选择状态传递给主机（例如呈现的数据点的颜色）。

新的选择状态（或筛选器）通过 update 方法中的 options.jsonFilters 属性进行通信。 jsonFilters 可以是 Advanced Filter 或 Tuple Filter。

• 如果视觉对象包含所选数据点，请使用 ISelectionManager 中的回调函数 registerOnSelectCallback将选择重置为所选书签的相应内容。

• 如果视觉对象使用筛选器来选择数据，请将筛选器值重置为所选书签的相应值。

带选择的视觉对象

如果视觉对象使用选择与其他视觉对象交互，则可通过以下两种方式之一添加书签支持：

• 使用 applySelectionFromFilter 通过 InteractivityService 来管理选择。 这是更简单的首选方法。

• 如果视觉对象不使用 InteractivityService，则通过 SelectionManager 管理。

使用 InteractivityService 还原书签选择

如果视觉对象使用 InteractivityService，则无需任何其他操作来支持视觉对象中的书签。

选择书签时，该实用程序将自动处理视觉对象的选择状态。

使用 SelectionManager 还原书签选择

如果不使用 InteractivityService，则可以使用 ISelectionManager.registerOnSelectCallback 方法保存和召回书签选择，如下所示：

选择书签时，Power BI 会使用相应的选择调用视觉对象的 callback 方法。

TypeScript复制

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

假设你在视觉对象的 visualTransform 方法中创建了一个数据点。

datapoints 如下所示：

TypeScript复制

visualDataPoints.push({
    category: categorical.categories[0].values[i],
    color: getCategoricalObjectValue(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 数组中的选择进行比较，并将相应的数据点标记为已选中。

TypeScript复制

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

更新数据点后，它们将反映存储在 filter 对象中的当前选择状态。 然后，当呈现数据点时，自定义视觉对象的选择状态将与书签的状态匹配。

带筛选器的视觉对象

若要在具有筛选器的视觉对象中支持书签，需要使用 InteractivityService。

假设视觉对象创建了一个按日期范围筛选数据的筛选器。 将 startDate 和 endDate 作为范围的开始日期和结束日期。

视觉对象创建高级筛选器并调用主机方法 applyJsonFilter 按相关条件筛选数据。

目标是用于筛选的表。

TypeScript复制

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 方法中，视觉对象检查对象中的筛选器：

TypeScript复制

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

如果 filter 对象不为 NULL，则视觉对象会从对象还原筛选条件：

TypeScript复制

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 值。

若要将属性值保存为筛选器状态，请在 capabilities.json 文件中将对象属性设置为 "filterState": true。