設定報表設定

發行項
07/15/2024

藉由使用Power BI用戶端 API，您可以在應用程式中內嵌 Power BI 分析。當您使用此用戶端連結庫內嵌 Power BI 報表時，您會提供 API 與該報表的相關信息。

您可以使用組態物件來儲存Power BI報表的相關信息。當您內嵌報表時，您接著會將該對象傳遞至 API。

除了授與 API 存取報表之外，您也可以使用組態對象來自定義報表的外觀和行為。例如，您可以調整組態物件中的篩選可見性、流覽存取和位置設定。

下列各節說明如何內嵌及設定Power BI內容。

提供組態資訊

IReportLoadConfiguration 介面會顯示組態物件可提供給 Power BI 用戶端 API 的相關報表屬性：

interface IReportLoadConfiguration {
    embedUrl: string;
    accessToken: string;
    id: string;
    groupId?: string;
    settings?: ISettings;
    bookmark?: IApplyBookmarkRequest;
    pageName?: string;
    filters?: ReportLevelFilters[];
    slicers?: ISlicer[];
    theme?: IReportTheme;
    contrastMode?: ContrastMode;
    datasetBinding?: IDatasetBinding;
    permissions?: Permissions;
    viewMode?: ViewMode;
    tokenType?: TokenType;
}

如需此介面必要參數的說明，以及示範如何內嵌報表的程式代碼範例，請參閱內嵌報表。

自訂設定

下列各節說明如何使用 settings 屬性來調整內嵌Power BI報表的外觀和行為。若要在報表已載入時更新報表設定，請使用 report.updateSettings 方法。如需詳細資訊，請參閱在運行時間更新報表設定。

窗格

使用單一 panes 屬性控制 Power BI 報表中所有窗格的外觀，如下列程式代碼所示：

let embedConfig = {
    ...
    settings: {
        panes: {
            bookmarks: {
                visible: true
            },
            fields: {
                expanded: false
            },
            filters: {
                expanded: false,
                visible: true
            },
            pageNavigation: {
                visible: false
            },
            selection: {
                visible: true
            },
            syncSlicers: {
                visible: true
            },
            visualizations: {
                expanded: false
            }
        }
    }
};

從下表中，您可以看到每個 panes 屬性支援的值：

財產	可見	擴大
`bookmarks`	✔	❌
`fields`	✔	✔
`filters`	✔	✔
`pageNavigation`	✔	❌
`selection`	✔	❌
`syncSlicers`	✔	❌
`visualizations`	✔	✔

篩選窗格

根據預設，會顯示篩選窗格。如果您要隱藏此窗格，請使用 filterPaneEnabled 屬性，如下列程式代碼所示：

let embedConfig = {
    ...
    settings: {
        filterPaneEnabled: false
    }
};

注意

panes 屬性會取代 filterPaneEnabled 屬性。為了維持回溯相容性，filterPaneEnabled 屬性仍然存在。不過，您應該避免同時使用這兩個屬性。

根據預設，內嵌報表會顯示頁面導覽箭號。若要隱藏這些箭號，請使用 navContentPaneEnabled 屬性，如下列程式代碼所示：

let embedConfig = {
    ...
    settings: {
        navContentPaneEnabled: false
    }
};

注意

panes 屬性會取代 navContentPaneEnabled 屬性。為了維持回溯相容性，navContentPaneEnabled 屬性仍然存在。不過，您應該避免同時使用這兩個屬性。

頁面瀏覽窗格會出現在報表底部，若要使用新的垂直頁面窗格，您可以設定 position 屬性：

let embedConfig = {
    ...
    settings: {
        panes:{
            pageNavigation: {
                visible: true,
                position: PagesPosition.Left
            }
        }    
    }
};

注意

您無法使用 updateSettings變更頁面瀏覽窗格的位置。

酒吧

使用 bars 屬性設定動作列和狀態列的可見性。

動作列

下列程式代碼可讓動作列顯示：

let embedConfig = {
    ...
    settings: {
        bars: {
            actionBar: {
                visible: true
            }
        }
    }
};

或者，在檢視模式中，也可以使用 actionBarEnabled URL 參數：

let embedConfig = {
   ...
   embedUrl: embedUrl + "&actionBarEnabled=true"
};

注意

在檢視模式中，只有組織案例內嵌支援動作列。

針對檢視模式中的動作列，建議啟用 Azure AD 應用程式的 UserState.ReadWrite.All 許可權。需要此許可權，使用者才能將報表新增至其我的最愛，以及啟用個人書籤和持續性篩選。

狀態列

狀態列會保留畫布縮放控制器，可提供縮放畫布的功能。

下列程式代碼會顯示狀態列：

let embedConfig = {
    ...
    settings: {
        bars: {
            statusBar: {
                visible: true
            }
        }
    }
};

地區設定

使用 localeSettings 屬性來指定內嵌報表的語言和格式：

localeSettings 中的 language 屬性由兩個字母的兩個部分組成，並以連字元分隔：

語言定義Power BI用於本地化的語言。語言範例包括 en en es （西班牙文），以及 tr （土耳其文）。
地區設定 定義 Power BI 用於日期、貨幣和其他相關內容的文字格式設定。地區設定的範例包括美國（英文）、ES（西班牙），以及 TR（Türkiye）。

如需可用語言和區域的清單，請參閱支援的語言。

下列程式代碼會將特定值指派給這些 localeSettings：

let embedConfig = {
    ...
    settings: {
        localeSettings: {
            language: "en-us"
        }
    }
};

注意

載入報表之後，就無法變更地區設定。若要變更報表地區設定，請呼叫 powerbi.reset(element)重設 iframe，然後再次內嵌報表。

透明背景

根據預設，內嵌內容的背景是白色，具有灰色邊界。如果您想要的話，您可以為內嵌內容提供透明背景。然後，您可以將您想要的樣式套用至包含內嵌內容的 HTML div 元素。 div 項目的樣式會變成可見。

使用此程式碼讓內嵌內容的背景變得透明：

let embedConfig = {
    ...
    settings: {
        background: models.BackgroundType.Transparent
    }
};

超連結點選行為

您可以控制數據表中超鏈接的行為，或現成的矩陣視覺效果。根據預設，超連結會開啟新的視窗。

可用的行為模式：

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}

Navigate - URL 會載入至新的瀏覽內容。
NavigateAndRaiseEvent - URL 會載入至新的瀏覽內容，並引發 dataHyperlinkClicked 事件。
RaiseEvent - 防止 URL 按兩下的預設行為，並引發 dataHyperlinkClicked 事件。

使用此程式代碼來變更連結的行為，以引發事件：

let embedConfig = {
    ...
    settings: {
        hyperlinkClickBehavior: HyperlinkClickBehavior.RaiseEvent
    }
};

點選現成資料表或矩陣視覺效果的超連結時，就會引發 dataHyperlinkClicked 事件，而且行為 NavigateAndRaiseEvent 或 RaiseEvent。

report.on('dataHyperlinkClicked', () => {
    ...
});

如需處理事件的詳細資訊，請參閱如何處理事件。

可視化轉譯的事件

您可以接聽每個轉譯視覺效果的事件。根據預設，視覺效果轉譯的事件會停用。

使用此程式代碼來觸發 visualRendered 事件：

let embedConfig = {
    ...
    settings: {
        visualRenderedEvents: true
    }
};

當視覺效果呈現且報表設定上啟用 visualRenderedEvents 時，就會引發 visualRendered 事件。

report.on('visualRendered', () => {
    ...
});

如需處理事件的詳細資訊，請參閱如何處理事件。

注意

由於視覺效果可能會因為用戶互動而轉譯，因此建議只在需要時開啟此事件。

錯誤訊息

如果您想要在內嵌報表中顯示自定義的錯誤訊息，請使用 hideErrors 屬性來隱藏預設的 Power BI 內嵌錯誤訊息。然後，您的程式代碼就可以以符合應用程式設計的方式處理錯誤事件。如需覆寫預設錯誤的詳細資訊，請參閱覆寫預設錯誤訊息。

使用此程式代碼來隱藏預設錯誤訊息：

let embedConfig = {
    ...
    settings: {
        hideErrors: true
    }
};

自訂選項

下列各節說明如何使用更多屬性進一步自定義內嵌Power BI報表的外觀和行為。

默認頁面

您可以控制內嵌報表的哪個頁面一開始出現。根據預設，初始頁面是您最近修改的頁面，這是您上次儲存報表時的作用中頁面。您可以使用 pageName 屬性來覆寫此行為，並提供您想要顯示的頁面名稱。不過，如果 Power BI 中沒有該名稱的頁面存在，則開啟它的要求會失敗。

下列程式代碼示範如何設定您的應用程式以顯示特定頁面：

let embedConfig = {
    ...
    pageName: 'ReportSection3'
};

載入篩選時

您可以控制應用程式套用至內嵌報表的篩選條件。根據預設，報表一開始會使用您儲存至報表的篩選。不過，如果您想要調整篩選條件，您有兩個選項：

設定更多篩選條件以與已儲存的篩選搭配使用。下列程式代碼示範如何使用 filters 屬性來附加更多篩選：
```
let embedConfig = {
    ...
    filters: [...]
};
```
以新的集合取代已儲存的篩選。 setFilters 方法提供動態變更報表篩選的方法。如果您在階段式內嵌期間使用此方法，您可以覆寫報表最初套用的篩選。如需建構篩選和使用 setFilters 方法的詳細資訊，請參閱控制報表篩選。

在負載交叉分析篩選器上

您可以控制應用程式套用至內嵌報表的交叉分析篩選器狀態。根據預設，API 會使用您儲存至報表的交叉分析篩選器。不過，您可以使用 slicers 屬性來修改現有交叉分析篩選器的狀態，如下列程式代碼所示：

embedConfig = {
    ...
    slicers: slicerArray,
};

如需修改交叉分析篩選器狀態的詳細資訊，請參閱控制報表交叉分析篩選器。

載入書籤時

藉由使用 bookmark 屬性，您可以將書籤套用至內嵌報表。如需使用書籤擷取目前設定之報表頁面檢視的詳細資訊，請參閱書籤。

您可以藉由提供書簽名稱或狀態來指定要使用的書籤。如果您提供書簽名稱，您的Power BI報表必須包含具有該名稱的已儲存書籤。

bookmark 屬性的類型為 IApplyBookmarkRequest. 下列程式代碼顯示此類型的定義：

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

此程式代碼示範如何依名稱指定書籤：

let embedConfig = {
    ...
    bookmark: {
        name: "Bookmark4f76333c3ea205286501"
    }
};

此程式代碼示範如何依狀態指定書籤：

let embedConfig = {
    ...
    bookmark: {
        state: bookmarkState
    }
};

主題和高對比度模式

您可以控制內嵌內容所使用的主題和對比層級。根據預設，您內嵌的任何內容會以預設主題和零對比顯示。您可以藉由設定特定主題或對比層級來覆寫此行為。如需主題的詳細資訊，請參閱套用報表主題。

可用的對比模式：

enum ContrastMode {
    None = 0,
    HighContrast1 = 1,
    HighContrast2 = 2,
    HighContrastBlack = 3,
    HighContrastWhite = 4
}

若要設定特定主題，請使用類似下列幾行的程式代碼：

let embedConfig = {
    ...
    theme: {themeJson: ...}
};

下列程式代碼示範如何覆寫預設對比層級，None：

let embedConfig = {
    ...
    contrastMode: models.contrastMode.HighContrast1
};

注意

API 無法同時套用主題和對比層級。如果您設定這兩個屬性，API 會使用您指定的對比層級，但會忽略 theme 設定。

縮放層級

若要深入瞭解如何調整報表縮放層級，請檢查輔助功能檔。

在編輯模式中開啟

根據預設，您內嵌的報表會出現在檢視模式中。不過，您可以覆寫此行為，以在編輯模式中開啟報表。您也可以在模式之間切換。

設定編輯模式

若要在編輯模式中開啟內嵌報表，請使用 viewMode 屬性與 permissions 屬性。

您可以指定下列值 viewMode 屬性：

View - 以檢視模式開啟報表。
Edit - 以編輯模式開啟報表。

您可以指定這些值 permissions 屬性：

Read - 使用者可以檢視報表。
ReadWrite - 使用者可以檢視、編輯及儲存報表。
Copy - 使用者可以使用 [另存新檔]來儲存報表的複本。
Create - 使用者可以建立新的報表。
All - 使用者可以建立、檢視、編輯、儲存及儲存報表複本。

當您將內容設定為在編輯模式中開啟時，請將適合編輯的值指派給 permissions 屬性值，如下列程式代碼所示：

let embedConfig = {
    ...
    permissions: models.Permissions.All
    viewMode: models.ViewMode.Edit
};

注意

您設定的 permissions 值只有在您取得的內嵌令牌具有足夠的許可權時才能運作。如需內嵌令牌的詳細資訊，請參閱建立內嵌令牌。

在編輯和檢視模式之間切換

除了指定要啟動內嵌內容的模式之外，您也可以動態切換編輯和檢視模式。

如果內容處於編輯模式，而且您想要切換至檢視模式，請使用下列 JavaScript 程式代碼：

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to view mode.
embeddedContent.switchMode("view");

如果內容處於檢視模式，而且您想要切換至編輯模式，請使用下列 JavaScript 程式代碼：

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to edit mode.
embeddedContent.switchMode("edit");

考慮和限制

當您設定內嵌內容時，請考慮下列幾點：

當顯示動作列時，無法變更頁面導覽位置。深入瞭解動作列。
當您在 setting 屬性中使用 bars 屬性時，如 Bars中所述，只有當內嵌內容處於編輯模式時，API 才會套用您的設定。如果您的內容處於檢視模式，API 會忽略 bars 設定。
當您使用 viewMode 屬性在編輯模式中顯示內容時，您需要採取兩個額外的步驟：
- 使用 permissions 屬性設定許可權等級。該許可權等級必須授與使用者修改內容的適當存取權。例如，如果您指派 permissions 值，Read, 用戶將無法編輯內容。
- 請確定您產生內嵌令牌具有支援編輯的許可權。例如，如果您取得具有 accessLevel 值的令牌，view, API 無法以編輯模式顯示內容。
panes 屬性會取代下列 settings 屬性：
- filterPaneEnabled
- navContentPaneEnabled
如果您使用 panes 屬性來設定篩選或頁面導覽可見性，請勿在應用程式中使用 filterPaneEnabled 或 navContentPaneEnabled 屬性。
API 無法同時將主題和對比層級套用至內嵌內容。如果您使用 theme 和 contrastMode 屬性來設定這兩個選項，API 會使用您的 contrastMode 值搭配內嵌內容。不過，API 會忽略 theme 設定。
如果您想要將書籤套用至內嵌報表，您可以使用 bookmark 屬性。如果您提供具有該屬性的書簽名稱，則 API 只能在該名稱存在書籤時使用書籤。同樣地，如果您使用 pageName 屬性來指定開啟頁面，則 API 只能顯示具有指定名稱的頁面。設定名稱之前，請考慮使用存取子方法，例如 Report getPages 方法，以檢查元件是否存在該名稱。

共用方式為

設定報表設定

提供組態資訊

自訂設定

窗格

篩選窗格

頁面瀏覽窗格

酒吧

動作列

狀態列

地區設定

透明背景

超連結點選行為

可視化轉譯的事件

錯誤訊息

自訂選項

默認頁面

載入篩選時

在負載交叉分析篩選器上

載入書籤時

主題和高對比度模式

縮放層級

在編輯模式中開啟

設定編輯模式

在編輯和檢視模式之間切換

考慮和限制

其他資源

共用方式為

設定報表設定

提供組態資訊

自訂設定

窗 格

篩選窗格

頁面瀏覽窗格

酒吧

動作列

狀態列

地區設定

透明背景

超連結點選行為

可視化轉譯的事件

錯誤訊息

自訂選項

默認頁面

載入篩選時

在負載交叉分析篩選器上

載入書籤時

主題和高對比度模式

縮放層級

在編輯模式中開啟

設定編輯模式

在編輯和檢視模式之間切換

考慮和限制

相關內容

其他資源

窗格