通过

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

  • 项目

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

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

支持书签的视觉对象

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

注意

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

  • Powerbi-visuals-utils-interactivityutils 版本 3.0.0 或更高版本，用于筛选器视觉对象以及使用 InteractivityService 的任何视觉对象。
  • 视觉对象 API 版本 1.11.0 或更高版本，用于使用 SelectionManager 而不是 InteractivityService 的非筛选器视觉对象。
  • 若要了解正在使用的版本，请检查 pbiviz.json 文件中的 apiVersion。

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 方法。

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 作为范围的开始日期和结束日期。

视觉对象创建高级筛选器并调用主机方法 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 值。

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

相关内容

什么是书签

在桌面报表中创建书签