共用方式為

使用書籤增強用戶的體驗

  • 發行項

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 - 報表書籤的顯示名稱，其會出現在 [Bookmarks] 窗格中。

  • 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 - 若要使用 個人化視覺效果來擷取目前狀態，請使用設定為 true的 personalizeVisuals 選項呼叫 capture 方法。

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

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

相關內容