使用书签增强用户体验

项目
07/21/2024

借助 Power BI 中的报表书签，可以捕获嵌入报表页的当前状态，包括所有筛选器及其视觉对象的状态。稍后打开报表时，可以选择书签以将报表还原到已保存状态。开发人员可以使用 Power BI 客户端 API 捕获和应用书签来控制用户体验。

保存的书签可以是作为报表的一部分保存的书签，也可以是作为报表的实时状态捕获的书签。如果在加载报表时应用保存的书签，可以通过提供书签的名称或其状态来指定要使用的书签。如果按名称提供书签，报表需要包含具有相同名称的已保存书签。

本文介绍需要嵌入支持书签的报表的不同 API 设置。

注意

在为组织嵌入的报表中，报表使用者通过捕获报表的状态来创建个人书签，并通过选择书签快速返回到该状态。有关详细信息，请参阅个人书签。

有关如何在为客户嵌入 的报表中创建类似体验的信息，请参阅捕获报表视图在 Power BI 嵌入式分析操场中展示。

有关在 Power BI 中使用书签的详细信息，请参阅在 Power BI Desktop 中创建书签。

有关在嵌入 Power BI 时使用个人书签的信息，请参阅个人书签。

如何使用报表书签

以下部分演示如何使用 Power BI 客户端 API 处理报表书签。

管理报表的书签

若要管理报表的书签，请使用嵌入报表实例的 bookmarksManager 属性。

BookmarksManager 类具有以下方法：

getBookmarks - 返回与报表关联的已保存书签的列表。
apply - 按名称将以前保存的书签应用于报表。
capture - 捕获并返回 base64 序列化字符串，该字符串表示报表的当前状态。
applyState 将以前捕获的 base64 序列化状态应用于报表。
play - 控制报表书签的幻灯片放映演示文稿模式。

访问报表书签

若要访问单个书签，请使用 getBookmarks 方法访问 ReportBookmark 对象列表。 ReportBookmark 类具有以下属性：

name - 报表书签的唯一标识符。
displayName - 报表书签的显示名称，显示在书签窗格中。
state - 报表书签状态的 base64 序列化。可以使用 bookmarksManager.applyState 方法将其保存并应用于报表。
children - 表示报表书签组的 ReportBookmark 对象列表（如果存在）。

使用报表书签 API

在嵌入式报表中，开发人员可以：

获取保存的报表书签列表。
在报表加载或会话期间按名称应用已保存的书签。
捕获并获取当前视图作为书签对象。
对报表加载或在会话期间应用捕获的书签状态
应用报表书签时执行其他逻辑。
显示或隐藏“书签”窗格。
进入或退出书签幻灯片放映模式。

获取已保存报表书签的列表

若要获取与报表关联的已保存书签列表，请调用报表的 bookmarksManager 属性返回的 BookmarksManager 对象的 getBookmarks 方法。

getBookmarks 方法的定义如下：

getBookmarks(): Promise<models.IReportBookmark[]>

例如：

let bookmarks = await report.bookmarksManager.getBookmarks();

在报表加载或会话期间按名称应用已保存的书签

若要使用其书签名称将以前保存的书签应用于报表，请调用报表的 bookmarksManager 属性返回的 BookmarksManager 对象的 apply 方法。

有关详细信息，请参阅配置报表设置。

apply 方法的定义如下：

apply(bookmarkName: string): Promise<void>

例如：

await report.bookmarksManager.apply("Bookmark1234");

捕获并获取作为书签对象的当前视图

若要将报表的当前状态捕获为 base64 字符串，请调用 BookmarksManager 对象的 capture 方法。 capture 方法返回一个 IReportBookmark 对象，该对象表示未保存在特定报表中的书签。使用 IReportBookmark.state 属性返回 base64 字符串，标识书签状态，稍后可以在加载时间或运行时应用于报表。

capture 方法的定义如下：

capture(options?:ICaptureBookmarkOptions): Promise<models.IReportBookmark>

例如：

let capturedBookmark = await report.bookmarksManager.capture();

捕获书签选项

还可以将 ICaptureBookmarkOptions 对象传递给 capture 方法。

interface ICaptureBookmarkOptions {
    allPages?: boolean;
    personalizeVisuals?: boolean;
}

allPages - 默认情况下，捕获的书签状态将仅保存当前页状态。若要捕获所有页面的状态，请调用 capture 方法，并将 allPages 选项设置为 true。
personalizeVisuals - 若要使用个性化视觉对象捕获当前状态，请调用 capture 方法，并将 personalizeVisuals 选项设置为 true。

例如，以下代码捕获所有页面的状态，包括个性化视觉对象：

let capturedBookmark = await report.bookmarksManager.capture({
    allPages: true,
    personalizeVisuals: true
});

在报表加载或会话期间应用捕获的书签状态

若要将以前捕获的书签状态应用于报表，请使用 BookmarksManager 对象的 applyState 方法。

有关详细信息，请参阅配置报表设置。

applyState 方法的定义如下：

applyState(state: string): Promise<void>

例如：

await report.bookmarksManager.applyState(capturedBookmark.state);

应用报表书签时执行其他逻辑

若要确定何时应用了报表书签，请通过调用报表对象的 on 方法来侦听 bookmarkApplied 事件。

例如：

report.on("bookmarkApplied", (event) => {
    console.log(event.detail.name);
});

显示或隐藏“书签”窗格

若要显示或隐藏 Power BI 书签窗格，请更新报表设置的 panes 属性。

显示“书签”窗格

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: true
        }
    }
};

隐藏“书签”窗格

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: false
        }
    }
};

有关更新报表设置的信息，请参阅配置报表设置。

进入或退出书签幻灯片放映模式

若要控制报表书签的幻灯片放映演示模式，请调用 BookmarksManager 对象的 play 方法。有关详细信息，请参阅书签作为幻灯片放映。

play 方法的定义如下：

play(playMode: models.BookmarksPlayMode): Promise<void>

注意

在进入书签幻灯片放映模式之前，请确保报表上至少有一个书签，getBookmarks API。

进入幻灯片放映演示模式

await report.bookmarksManager.play(models.BookmarksPlayMode.Presentation);

退出幻灯片放映演示模式

await report.bookmarksManager.play(models.BookmarksPlayMode.Off);

注意事项和限制

使用书签 API 时，对报表的某些更改可能会导致错误或意外结果。其中一个示例是从报表中删除报表筛选器。若要避免错误，必须存在相应的筛选器卡。不要删除筛选器，而是将其值设置为 All。如果不知道删除或更改了哪些筛选器，请将更改应用到报表后重新捕获书签。
加载筛选器（如由嵌入会话创建或由更新筛选器添加操作添加）的筛选器在书签状态中捕获，但仅在当前会话中应用。若要克服此限制，应使用 All 值将筛选器保存到报表上，并使用更新筛选器更新操作在嵌入会话中修改。

通过