設定報表設定

藉由使用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 方法，以檢查元件是否存在該名稱。

Last updated on 2024-07-15

共用方式為