向视觉对象添加显示警告图标

在 Power BI 视觉对象中，显示警告图标可以通知用户可能的问题或错误。 在许多情况下，显示警告图标可能很有用，下面是一些示例：

• 当值超出纬度或经度有效范围时，地图视觉对象可以显示警告图标。

• 饼图视觉对象在显示与正值混合的负值时可以显示警告图标。

• 计算无穷大值时，笛卡尔图可以显示警告图标。 例如，如果 Y 为零，当 X 除以 Y 时，结果为无穷大 。

当图标出现时，用户可以将鼠标悬停在该图标上，以查看警告消息的标题。

当用户选择警告图标时，弹出窗口中会显示一条描述问题的消息。

创建警告图标

可以创建一个警告图标，使其包含针对正在设计的视觉对象的自定义消息。 是否引发警告图标由你决定。 如以下示例所示，当显示警告图标时，视觉对象将继续运行。

添加对更新方法的调用

要将显示警告图标添加到视觉对象上，首先需要调用 displayWarningIcon 方法。 该方法是 IVisualHost 的一部分，使用 powerbi-visuals-api 公开。

将以下导入添加到文件：

Javascript复制

import powerbiVisualsApi from "powerbi-visuals-api"; 

添加导入后，需要添加一个条件，用于确定何时显示警告图标。 使用以下示例查看两个可选条件。 这些示例的完整代码可在 barChart.ts 中找到，该文件是 PowerBI-visuals-sampleBarChart 存储库的一部分。

示例 1 - 检查语言兼容性

本地化用于显示客户母语的视觉对象，该语言取决于操作系统的设置。

在此示例中，视觉对象将视觉对象的语言（设置为美式英语）与操作系统的语言进行比较。 如果语言不匹配，将显示警告图标。

Javascript复制

if (this.locale != 'en-US') { 

            this.host.displayWarningIcon('Language mismatch', 'This visual does not support languages other than english. Please use US english as your browser language.'); 

        }

示例 2 - 比较相邻列中的颜色

在此示例中，当相邻的两列具有相同的颜色时，将出现显示警告图标。

getColumnColorByIndex 方法循环访问所有列。 如果两个相邻列具有相同的颜色，则会显示警告图标。

Javascript复制

let category = options.dataViews[0].categorical.categories[0]; 

let dataValue = options.dataViews[0].categorical.values[0]; 

let colorPalette = this.host.colorPalette; 

for (let i = 0, len = Math.max(category.values.length, dataValue.values.length); i -1; i++) { 

    const color1: string = getColumnColorByIndex(category, i, colorPalette); 

    const color2: string = getColumnColorByIndex(category, i+1, colorPalette); 

    if (color1 == color2) { 

        this.host.displayWarningIcon('same colors', 'there are two neighbor columns with the same color. please use the data color property to change it.'); 

    } 

} 

注意事项

• 不是由视觉对象导致的错误或警告（例如派生自 Power BI 服务的“值太多，未显示所有数据”错误）在视觉对象调用之前传播，并优先于源自于你的视觉对象代码中的错误。 如果在加载数据时出现错误，则在运行该视觉对象的代码并满足显示警告图标条件之前，将显示该错误，而不显示显示警告图标错误。

• 在每次视觉对象呈现时（例如，将新数据拖动到视觉对象中时），都会清除显示警告。 呈现视觉对象后，将调用视觉对象的 update() 方法。 因此，如果基于在更新方法中检查的条件引发视觉对象的警告，则每次呈现该视觉对象时，如果满足条件，将再次显示该警告。

• 调整视觉对象的大小不会影响警告图标。

注意事项和限制

以下限制是指显示图标文本：

• 标题的最大长度为 70 个字符

• 文本的最大长度为 2000 个字符

• 文本仅显示为纯文本