配置报告设置
- 版本 ：2023.1(当前版本)
配置报告设置
通过使用 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 报表中所有窗格的外观，如以下代码所示：
Javascript
复制
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属性，如以下代码所示：
Javascript
复制
let embedConfig = {
...
settings: {
filterPaneEnabled: false
}
};
备注
panes属性替换了filterPaneEnabled属性。为了保持向后兼容性，该filterPaneEnabled属性仍然存在。但是，您应该避免同时使用这两个属性。
页面导航窗格
默认情况下，页面导航箭头在嵌入式报表中可见。要隐藏这些箭头，请使用该navContentPaneEnabled属性，如以下代码所示：
Javascript
复制
let embedConfig = {
...
settings: {
navContentPaneEnabled: false
}
};
备注
panes属性替换了navContentPaneEnabled属性。为了保持向后兼容性，该navContentPaneEnabled属性仍然存在。但是，您应该避免同时使用这两个属性。
页面导航窗格出现在报表的底部，要使用新的垂直页面窗格，您可以设置position属性：
Javascript
复制
let embedConfig = {
...
settings: {
panes:{
pageNavigation: {
visible: true,
position: PagesPosition.Left
}
}
}
};
备注
您不能使用 更改页面导航窗格的位置updateSettings。
酒吧
使用 属性设置操作栏和状态栏的可见bars性。
操作栏
以下代码使操作栏可见：
Javascript
复制
let embedConfig = {
...
settings: {
bars: {
actionBar: {
visible: true
}
}
}
};
或者，在视图模式下，也可以使用actionBarEnabledURL 参数：
打字稿
复制
let embedConfig = {
...
embedUrl: embedUrl + "&actionBarEnabled=true"
};
备注
在视图模式下，操作栏仅支持嵌入您的组织场景。
对于视图模式下的操作栏，建议UserState.ReadWrite.All为 Azure AD 应用程序启用权限。需要此权限才能允许最终用户将报告添加到他们的收藏夹，以及启用个人书签和永久过滤器。
状态栏
状态栏包含画布缩放控制器，它提供了在画布上缩放的功能。
以下代码使状态栏可见：
Javascript
复制
let embedConfig = {
...
settings: {
bars: {
statusBar: {
visible: true
}
}
}
};
区域设置
使用该localeSettings属性指定嵌入报告的语言和格式：
中的language属性localeSettings由两部分组成，每部分两个字母，用连字符分隔：
language定义 Power BI 用于本地化的语言。语言示例包括en（英语）、es（西班牙语）和tr（土耳其语）。
区域设置定义 Power BI 用于日期、货币和其他相关内容的文本格式。区域设置的示例包括US（英语）、ES（西班牙）和TR（土耳其）。
有关可用语言和地区的列表，请参阅支持的语言。
以下代码为这些分配了特定的值localeSettings：
Javascript
复制
let embedConfig = {
...
settings: {
localeSettings: {
language: "en-us"
}
}
};
备注
加载报表后无法更改区域设置。要更改报表区域设置，请通过调用重置 iframe powerbi.reset(element)，然后再次嵌入报表。
透明背景
默认情况下，嵌入内容的背景为白色，边缘为灰色。如果您愿意，可以为嵌入的内容提供透明背景。然后您可以将您想要的样式应用到div包含嵌入内容的 HTML 元素。元素的div样式然后变得可见。
使用此代码使嵌入内容的背景透明：
Javascript
复制
let embedConfig = {
...
settings: {
background: models.BackgroundType.Transparent
}
};
超链接点击行为
您可以控制表中超链接的行为，或矩阵开箱即用的视觉效果。默认情况下，超链接将打开一个新窗口。
下面列出了可用的行为模式：
打字稿
复制
enum HyperlinkClickBehavior {
Navigate,
NavigateAndRaiseEvent,
RaiseEvent
}
Navigate- URL 将被加载到新的浏览上下文中。
NavigateAndRaiseEvent- 该 URL 将被加载到一个新的浏览上下文中，并将引发一个dataHyperlinkClicked事件。
RaiseEvent- 防止 URL 单击和引发dataHyperlinkClicked事件的默认行为。
使用此代码更改链接的行为以引发事件：
Javascript
复制
let embedConfig = {
...
settings: {
hyperlinkClickBehavior: HyperlinkClickBehavior.RaiseEvent
}
};
当dataHyperlinkClicked在开箱即用的表格或矩阵视觉对象上单击超链接并且行为是NavigateAndRaiseEvent或时，将触发事件RaiseEvent。
Javascript
复制
report.on('dataHyperlinkClicked', () => {
...
});
有关处理事件的更多信息，请参阅如何处理事件。
视觉渲染事件
您可以为每个呈现的视觉效果收听一个事件。默认情况下，视觉渲染事件是禁用的。
使用此代码使visualRendered事件触发：
Javascript
复制
let embedConfig = {
...
settings: {
visualRenderedEvents: true
}
};
visualRendered呈现视觉效果并visualRenderedEvents在报告设置中启用时会触发一个事件。
Javascript
复制
report.on('visualRendered', () => {
...
});
有关处理事件的更多信息，请参阅如何处理事件。
备注
由于视觉效果可能会因用户交互而呈现，因此建议仅在需要时打开此事件。
错误讯息
如果您想在嵌入式报表中显示自定义错误消息，请使用该hideErrors属性隐藏默认的 Power BI 嵌入式错误消息。然后，您的代码可以以适合您的应用程序设计的方式处理错误事件。有关覆盖默认错误的更多信息，请参阅覆盖默认错误消息。
使用此代码隐藏默认错误消息：
Javascript
复制
let embedConfig = {
...
settings: {
hideErrors: true
}
};
自定义选项
以下部分介绍如何使用其他属性进一步自定义嵌入式 Power BI 报表的外观和行为。
默认页面
您可以控制最初显示嵌入报告的哪一页。默认情况下，初始页面是您最近修改的页面，它是您上次保存报表时的活动页面。pageName您可以通过使用该属性并为其提供您要显示的页面的名称来覆盖此行为。但是，如果 Power BI 中不存在具有该名称的页面，则打开它的请求将失败。
以下代码显示了如何配置您的应用程序以显示特定页面：
Javascript
复制
let embedConfig = {
...
pageName: 'ReportSection3'
};
加载过滤器
您可以控制应用程序应用于嵌入式报告的过滤器。默认情况下，报告最初使用您保存到报告中的过滤器。但是，如果要调整过滤器，您有两个选择：
配置其他过滤器以与保存的过滤器一起使用。以下代码显示了如何使用该filters属性附加其他过滤器：
Javascript
复制
let embedConfig = {
...
filters: [...]
};
用一组新的过滤器替换保存的过滤器。该setFilters方法提供了一种动态更改报表过滤器的方法。如果您在分阶段嵌入期间使用此方法，则可以覆盖报表最初应用的过滤器。有关构建过滤器和使用该setFilters方法的更多信息，请参阅控制报告过滤器。
加载切片器
您可以控制应用程序应用于嵌入式报表的切片器的状态。默认情况下，API 使用您保存到报告中的切片器。但是，您可以使用该slicers属性修改现有切片器的状态，如以下代码所示：
Javascript
复制
embedConfig = {
...
slicers: slicerArray,
};
有关修改切片器状态的更多信息，请参阅控制报告切片器。
加载书签
通过使用该bookmark属性，您可以将书签应用于嵌入式报表。有关使用书签捕获当前配置的报告页面视图的更多信息，请参阅书签。
您可以通过提供书签名称或状态来指定要使用的书签。如果您提供书签名称，您的 Power BI 报表需要包含一个使用该名称的已保存书签。
该bookmark属性的类型IApplyBookmarkRequest.以下代码显示了此类型的定义：
打字稿
复制
type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;
interface IApplyBookmarkStateRequest {
state: string;
}
interface IApplyBookmarkByNameRequest {
name: string;
}
此代码显示如何按名称指定书签：
Javascript
复制
let embedConfig = {
...
bookmark: {
name: "Bookmark4f76333c3ea205286501"
}
};
此代码显示如何按状态指定书签：
Javascript
复制
let embedConfig = {
...
bookmark: {
state: bookmarkState
}
};
主题和高对比度模式
您可以控制嵌入内容使用的主题和对比度级别。默认情况下，您嵌入的任何内容都以默认主题和零对比度显示。您可以通过配置特定主题或对比度级别来覆盖此行为。有关主题的更多信息，请参阅应用报表主题。
下面列出了可用的对比度模式：
打字稿
复制
enum ContrastMode {
None = 0,
HighContrast1 = 1,
HighContrast2 = 2,
HighContrastBlack = 3,
HighContrastWhite = 4
}
使用类似于以下行的代码来配置特定主题：
Javascript
复制
let embedConfig = {
...
theme: {themeJson: ...}
};
以下代码显示了如何覆盖默认对比度级别None：
Javascript
复制
let embedConfig = {
...
contrastMode: models.contrastMode.HighContrast1
};
备注
API 不能同时应用主题和对比度级别。如果同时配置这两个属性，API 会使用您指定的对比度级别但会忽略该theme设置。
缩放级别
要了解有关调整报告缩放级别的更多信息，请查看辅助功能文档。
以编辑模式打开
默认情况下，您嵌入的报告以查看模式显示。但是，您可以覆盖此行为以在编辑模式下打开报表。您还可以在模式之间切换。
配置编辑模式
要以编辑模式打开嵌入式报表，请将viewMode属性与 属性一起使用permissions。
您可以为该属性分配viewMode以下值：
View- 在查看模式下打开报告。
Edit- 在编辑模式下打开报告。
您可以为属性分配permissions这些值：
Read- 用户可以查看报告。
ReadWrite- 用户可以查看、编辑和保存报告。
Copy- 用户可以使用另存为保存报告的副本。
Create- 用户可以创建新报告。
All- 用户可以创建、查看、编辑、保存和保存报告的副本。
当您将内容配置为以编辑模式打开时，请为该permissions属性分配一个适合编辑的值，如以下代码所示：
Javascript
复制
let embedConfig = {
...
permissions: models.Permissions.All
viewMode: models.ViewMode.Edit
};
备注
您配置的permissions值仅在您获取的嵌入令牌具有足够权限时才有效。有关嵌入令牌的更多信息，请参阅创建嵌入令牌。
在编辑和查看模式之间切换
除了指定嵌入内容的启动模式外，您还可以在编辑和查看模式之间动态切换。
如果内容处于编辑模式，而您想切换到查看模式，请使用此 JavaScript 代码：
Javascript
复制
// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);
...
// Switch to view mode.
embeddedContent.switchMode("view");
如果内容处于查看模式，而您想切换到编辑模式，请使用此 JavaScript 代码：
Javascript
复制
// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);
...
// Switch to edit mode.
embeddedContent.switchMode("edit");
注意事项和限制
配置嵌入内容时请考虑以下几点：
当操作栏可见时，无法更改页面导航位置。了解有关操作栏的更多信息。
当您在bars属性中使用setting属性时，如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 方法）来检查是否存在具有该名称的组件。