配置报表设置

项目
07/17/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
    }
};

注意

窗格属性替换 filterPaneEnabled 属性。为了保持向后兼容性，filterPaneEnabled 属性仍然存在。但是，应避免结合使用这两个属性。

默认情况下，页面导航箭头在嵌入报表上可见。若要隐藏这些箭头，请使用 navContentPaneEnabled 属性，如以下代码所示：

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

注意

窗格属性替换 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（英语）、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 属性时，如栏中所述，仅当嵌入内容处于编辑模式时，API 才应用配置。如果内容处于视图模式，API 将忽略 bars 设置。
使用 viewMode 属性在编辑模式下显示内容时，需要执行两个步骤：
- 使用 permissions 属性配置权限级别。该权限级别需要向用户授予修改内容的适当访问权限。例如，如果分配 permissions 值 Read, 用户将无法编辑内容。
- 确保生成的嵌入令牌具有支持编辑的权限。例如，如果获取具有 accessLevel 值的令牌 view, API 无法在编辑模式下显示内容。
窗格属性替换以下 settings 属性：
- filterPaneEnabled
- navContentPaneEnabled
如果使用 panes 属性配置筛选器或页面导航可见性，请不要在应用中使用 filterPaneEnabled 或 navContentPaneEnabled 属性。
API 不能同时将主题和对比度级别应用于嵌入内容。如果使用 theme 和 contrastMode 属性配置这两个选项，API 会将 contrastMode 值与嵌入的内容一起使用。但是，API 会忽略 theme 设置。
如果要将书签应用于嵌入报表，可以使用 bookmark 属性。如果提供具有该属性的书签名称，则 API 只能使用该名称的书签。同样，如果使用 pageName 属性指定打开页，则 API 只能显示具有给定名称的页面。在配置名称之前，请考虑使用访问器方法（如 Report getPages 方法），以检查是否存在具有该名称的组件。

通过