隐藏或显示视觉对象标头
嵌入应用中的 Power BI 报表包含视觉对象,例如图表、热度地图和仪表。 这些视觉对象具有标头,使操作可供用户使用。 使用 Power BI 时,可以在报表中隐藏或显示每个视觉对象的标题。 每个视觉对象在“可视化效果”窗格的“格式设置”部分中都有一张卡片,称为“视觉对象”标头。 可以使用该卡打开和关闭视觉对象的标题。 详细了解 Visual 标头中的视觉对象标头。
视觉对象标头中的操作示例包括:
- 在焦点模式下打开视觉对象。
- 向下钻取或向上钻取。
- 查看当前应用于视觉对象的筛选器和切片器。
- 打开视觉对象的选项菜单。
有时隐藏这些操作很有用。 例如,当两个视觉对象重叠时,你可能不想显示两个视觉对象的标头。
此 API 提供了一种隐藏或显示报表中所有视觉对象或仅显示特定视觉对象的标头的方法。 可以配置报表加载的可见性,也可以调用报表 updateSettings
方法来更改报表加载后的可见性,请参阅 运行时更新报表设置。
可以在许多方案中使用 API,包括以下用例:
- 仅隐藏报表中的某些视觉对象标题。
- 在应用(如按钮单击)中使用业务逻辑,在加载报表后隐藏或显示标头。
如何隐藏或显示视觉对象标头
若要在 API 中隐藏或显示视觉对象标头,请在报表的设置中配置某些参数。 有关在嵌入报表中配置选项的常规信息,请参阅 “配置报表设置 ”。
视觉对象标头设置
使用视觉对象标头时,可见性当前是唯一可以配置的设置。 若要隐藏或显示标头,请提供视觉标头配置对象列表。 每个对象都包含设置对象,还可以包含选择器。 选择器 标识要向其应用设置的视觉对象。 详细了解 选择器中的选择器。
提供给 API 的配置对象的类型为 IVisualSettings。 本文的后面部分将介绍如何在代码中使用此接口 的示例 。 Power BI 模型 列出了示例使用的所有接口定义。
请注意以下几点:
- 选择器在这些设置中是可选的。 如果未列出任何选择器,API 会将设置应用于报表中的所有视觉对象。
- 使用选择器时,可以按名称或按类型指定视觉对象。 若要获取给定页面中视觉对象的名称和类型,请使用 Page getVisuals 方法。
优先规则
API 按以下顺序应用配置设置:
- 保存在报表中的设置。
- 在嵌入配置对象中定义的设置,API 在加载时适用。
- 提供给
updateSettings
API 的设置。
如果多个设置可以应用于视觉对象,API 将使用应用的最后一个设置。 下一部分中 的“隐藏所有视觉对象标头 ”示例说明了这一点。
示例
这些示例演示了使用 API 隐藏或显示视觉标头的不同方法。
隐藏所有视觉对象标头
此简单方案通过隐藏报表中的所有视觉对象标头,为客户提供干净的报表视图:
let embedConfig = {
...
settings: {
...
visualSettings: {
visualHeaders: [
{
settings: {
visible: false
}
/* No selector is listed. The API hides the headers of all the visuals in the report. */
}
]
}
}
};
...
let report = powerbi.embed(embedContainer, embedConfig);
隐藏特定视觉对象的标头
此示例使用选择器将可见性设置应用于单个视觉对象。 当想要隐藏对视觉对象没有意义的功能时,会出现此方案。 在这种情况下,请使用以下代码:
let embedConfig = {
...
settings: {
...
visualSettings: {
visualHeaders: [
{
settings: {
visible: false
},
selector: {
$schema: "http://powerbi.com/product/schema#visualSelector",
visualName: <The name of the visual> // You can retrieve the name by using getVisuals.
}
}
]
}
}
};
...
let report = powerbi.embed(embedContainer, embedConfig);
隐藏所有视觉对象标头
使用此代码可隐藏报表中的所有视觉对象标头,但特定视觉对象的标头除外:
let embedConfig = {
...
settings: {
...
visualSettings: {
visualHeaders: [
{
settings: {
visible: false
}
/* No selector is listed. The API hides the headers of all the visuals in the report. */
},
{
settings: {
visible: true
},
selector: {
$schema: "http://powerbi.com/product/schema#visualSelector",
visualName: <The name of the visual> // You can retrieve the name by using getVisuals.
}
}
]
}
}
};
...
let report = powerbi.embed(embedContainer, embedConfig);
如果要使多个标头可见,可以扩展此代码。 设置其他实例 IVisualHeader
,并将 visible
参数 settings
设置为 true
. 对于每个应具有可见标头的视觉对象,请将一个 IVisualHeader
实例添加到列表中。
限制
- 如果嵌入的报表处于视图模式,则只能控制视觉对象标头的可见性。
- 只能隐藏或显示视觉对象的整个标头。 无法在标题菜单中配置特定项的可见性。
- 使用选择器指定视觉对象的名称或类型时,请使用 Page getVisuals 方法获取视觉对象的名称,该名称是唯一标识符。 不要使用视觉对象的标题配置选择器。
- 如果用户保存使用 API 嵌入的报表,则定义的视觉设置将保存到报表中。 可以通过配置具有权限级别而不是
Edit
权限Save
级别的View
报表来避免这种情况。