使用書簽增強使用者的體驗

發行項
09/17/2023

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

在內嵌報表中，開發人員可以：

取得已儲存的報表書簽清單。
依報表載入或會話期間的名稱套用已儲存的書簽。
擷取並取得目前檢視做為書簽物件。
在報表載入或會話期間套用擷取的書簽狀態
套用報表書簽時，請執行其他邏輯。
顯示或隱藏 [書簽] 窗格。
進入或結束書簽投影片放映模式。

取得已儲存的報表書簽清單

若要取得與報表相關聯的已儲存書簽清單，請呼叫 getBookmarks 報表 bookmarksManager 屬性所傳回的BookmarksManager物件方法。

方法 getBookmarks 的定義如下：

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

例如：

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

依報表載入或會話期間的名稱套用已儲存的書簽

若要使用先前儲存的書簽名稱將先前儲存的書簽套用至報表，請呼叫 apply 報表 bookmarksManager 屬性所傳回BookmarksManager物件的方法。

如需詳細資訊，請參閱設定報表設定。

方法 apply 的定義如下：

apply(bookmarkName: string): Promise<void>

例如：

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

擷取並取得目前檢視做為書簽物件

若要將報表的目前狀態擷取為 base64 字串，請呼叫 captureBookmarksManager 物件的方法。方法 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- 若要使用個人化視覺效果擷取目前狀態，請使用設定為 true 的選項呼叫 capture 方法 personalizeVisuals 。

例如，下列程式碼會擷取所有頁面的狀態，包括個人化視覺效果：

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

在報表載入或會話期間套用擷取的書簽狀態

若要將先前擷取的書簽狀態套用至報表，請使用 applyStateBookmarksManager 物件的方法。

如需詳細資訊，請參閱設定報表設定。

方法 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
        }
    }
};

如需更新報表設定的資訊，請參閱設定報表設定。

進入或結束書簽投影片放映模式

若要控制報表書簽的投影片放映簡報模式，請呼叫 playBookmarksManager 物件的方法。如需詳細資訊，請參閱書簽作為投影片放映。

方法 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 值儲存在報表上，並使用更新篩選更新作業在內嵌會話中修改。

共用方式為