個人化報表配置

發行項
09/17/2023

使用自訂報表配置，您可以使用與原始報表中儲存的版面配置不同的版面配置來內嵌 Power BI 報表。當您定義自訂報表配置時，可以變更報表頁面的大小，並控制頁面上視覺效果的大小、位置和可見度。

自訂版面配置概觀

若要建立自訂報表配置，請定義自訂版面設定物件，並將它傳遞給內嵌組態中的設定物件。

在 settings 物件中，將設定 layoutType 為 models.LayoutType.Custom ，並設定 customLayout 為自訂版面設定物件：

let embedConfig = {
    ...
    settings: {
        layoutType: models.LayoutType.Custom
        customLayout: {...}
    }
};

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

如何定義自訂報表配置

每個自訂報表配置都會以您定義的自訂版面設定物件來表示，以指定頁面大小、畫布縮放比例和頁面版面配置。在頁面配置中，您可以為每個視覺效果指定視覺配置，以及報表的預設視覺效果配置。

自訂配置介面定義

ICustomLayout使用介面來定義自訂設定物件：

interface ICustomLayout {
    pageSize?: IPageSize;
    displayOption?: DisplayOption;
    pagesLayout?: PagesLayout;
}

ICustomLayout介面具有下列屬性：

pageSize - 物件 IPageSize ，定義報表畫布區域的頁面大小。

interface IPageSize {
    type: PageSizeType;
}

物件 IPageSize 會 PageSizeType 使用列舉來設定頁面大小：

enum PageSizeType {
    Widescreen,
    Standard,
    Cortana,
    Letter,
    Custom
}

displayOptionDisplayOption- 列舉，控制如何調整畫布以符合框架。
```
enum DisplayOption {
    FitToPage,
    FitToWidth,
    ActualSize
}
```
pagesLayout - 物件 PagesLayout ，控制頁面上每個視覺效果的配置。此屬性會將頁面名稱對應至 PageLayout 物件。如需詳細資訊，請參閱定義頁面版面配置。
```
type PagesLayout = { [key: string]: IPageLayout; }
```

定義頁面版面配置

IPageLayout使用介面來定義頁面版面設定物件。介面可讓您定義視覺化版面配置對應，將每個視覺效果名稱對應至新的版面設定物件，以及預設的視覺配置。定義頁面版面配置是選擇性的。如果您未提供報表的配置，Power BI 會將預設配置套用至報表。也就是說，預設配置適用于您未在視覺效果設定物件中指定的所有視覺效果。例如，您可以一開始隱藏報表中的所有視覺效果，然後在您選擇的版面配置中顯示選取的視覺效果。

interface IPageLayout {
    defaultLayout: IVisualLayout,
    visualsLayout: { [key: string]: IVisualLayout; };
}

IPageLayout介面具有下列屬性：

defaultLayoutIVisualLayout- 定義預設視覺配置的物件。預設配置會自動套用至報表頁面上的所有視覺效果。
```
defaultLayout?: IVisualLayout
```
visualsLayout - 物件 VisualsLayout ，定義報表頁面上視覺效果名稱與視覺效果版面配置之間的對應。
```
visualsLayout: VisualsLayout
```
```
VisualsLayout = { [key: string]: IVisualLayout; }
```

定義視覺效果配置

若要定義視覺配置，請使用 IVisualLayout 介面來建立視覺設定物件，並設定其位置、大小和可見度。

interface IVisualLayout {
    x?: number;
    y?: number;
    z?: number;
    width?: number;
    height?: number;
    displayState?: IVisualContainerDisplayState;
}

IVisualLayout介面具有下列屬性：

x， y ， z - 定義視覺效果的 x、y 和 z 座標。
width， height - 定義視覺效果的寬度和高度。
displayStateIVisualContainerDisplayState- 定義視覺效果可見度的物件。
```
interface IVisualContainerDisplayState {
    mode: VisualContainerDisplayMode;
}
```
物件 IVisualContainerDisplayState 會 VisualContainerDisplayMode 使用列舉來設定可見度：
```
enum VisualContainerDisplayMode {
    Visible,
    Hidden
}
```

更新配置

若要在報表已載入時更新報表配置，請使用 report.updateSettings 方法。如需詳細資訊，請參閱在執行時間更新報表設定。

範例

這個完整的程式碼範例示範如何使用自訂報表配置來內嵌報表。除了兩個視覺效果之外，所有視覺效果都會隱藏： VisualContainer1 和 VisualContainer2。 VisualContainer1 具有新的版面配置、位置和大小，而 VisualContainer2 則以報表的預設版面配置顯示。

// Get models. Models contains enums that can be used.
let models = window['powerbi-client'].models;

let embedConfig = {
    type: 'report',
    id: reportId,
    embedUrl: 'https://app.powerbi.com/reportEmbed',
    tokenType: models.TokenType.Embed,
    accessToken: 'H4...rf',
    settings: {
        layoutType: models.LayoutType.Custom
        customLayout: {
            pageSize: {
                type: models.PageSizeType.Custom,
                width: 1600,
                height: 1200
            },
            displayOption: models.DisplayOption.ActualSize,
            pagesLayout: {
                "ReportSection1" : {
                    defaultLayout: {
                        displayState: {
                            mode: models.VisualContainerDisplayMode.Hidden
                        }
                    },
                    visualsLayout: {
                        "VisualContainer1": {
                            x: 1,
                            y: 1,
                            z: 1,
                            width: 400,
                            height: 300,
                            displayState: {
                                mode: models.VisualContainerDisplayMode.Visible
                            }
                        },
                        "VisualContainer2": {
                            displayState: {
                                mode: models.VisualContainerDisplayMode.Visible
                            }
                        },
                    }
                }
            }
        }
    }
};
...
// Embed the report and display it within the div container.
let report = powerbi.embed(embedContainer, embedConfig);

下一步

取得頁面和視覺效果

進行報告設定