个性化报表布局

项目
09/17/2023

使用自定义报表布局，可以嵌入与原始报表中保存的布局不同的 Power BI 报表。定义自定义报表布局时，可以改变报表页的大小，并控制页面上视觉对象的大小、位置和可见性。

自定义布局概述

若要创建自定义报表布局，请定义自定义布局对象，并将其传递给嵌入配置中的设置对象。

在设置对象中，设置为layoutTypemodels.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
}

displayOption - 一个 DisplayOption 枚举，用于控制如何缩放画布以适应框架。
```
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 接口具有以下属性：

defaultLayout - 定义 IVisualLayout 默认视觉布局的对象。默认布局会自动应用于报表页上的所有视觉对象。
```
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 - 定义视觉对象的宽度和高度。
displayState - 定义 IVisualContainerDisplayState 视觉对象的可见性的对象。
```
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);

后续步骤

获取页面和视觉对象

配置报告设置