進行報告設定

發行項
01/18/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"
};

注意

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

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

狀態列

狀態列會保留畫布縮放控制器，其可讓您縮放畫布。

下列程式代碼可讓狀態列顯示：

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

地區設定

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

中的 languagelocaleSettings 屬性包含兩個字母的兩個部分，分別以連字元分隔：

語言會定義 Power BI 用於本地化的語言。語言範例包括 en (English) 、 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
    }
};

轉 visualRendered 譯視覺效果並在 visualRenderedEvents 報表設定上啟用時引發事件。

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");

考量與限制

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

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

共用方式為