隐藏或显示视觉对象标头

项目
07/17/2024

嵌入应用中的 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);

如果要使多个标头可见，可以扩展此代码。使用设置为 truesettings 中的 visible 参数设置 IVisualHeader 的其他实例。对于每个应具有可见标头的视觉对象，请将一个 IVisualHeader 实例添加到列表中。

注意事项和限制

如果嵌入的报表处于视图模式，则只能控制视觉对象标头的可见性。
只能隐藏或显示视觉对象的整个标头。无法在标题菜单中配置特定项的可见性。
使用选择器指定视觉对象的名称或类型时，请使用 Page getVisuals 方法获取视觉对象的名称，这是唯一标识符。不要使用视觉对象的标题配置选择器。
如果用户保存使用 API 嵌入的报表，则定义的视觉设置将保存到报表中。可以通过配置权限级别为 View 而不是 Edit 或 Save的报表来避免这种情况。

通过