通过

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

  • 项目

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

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

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

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

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

A screenshot showing a warning icon in a Power BI visual.

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

A screenshot showing a warning message triggered by selecting a warning icon in a Power BI visual.

创建警告图标

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

添加对更新方法的调用

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

将以下导入添加到文件：

import powerbiVisualsApi from "powerbi-visuals-api";

添加导入内容后，再添加一个条件，用于确定何时显示警告图标。 请使用本文中的示例来查看两个可选条件。

示例 1：检查语言兼容性

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

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

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

            this.host.displayWarningIcon('Language inconsistency', 'This visual supports only US English. For the visual to work as expected, set your browser's language to US English.'); 
        }

A screenshot showing the language mismatch warning message.

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

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

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

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 < len-1; i++) { 

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

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

    if (color1 == color2) { 

        this.host.displayWarningIcon('Adjacent columns have the same color.', 'Columns that are next to each other have the same color. To change a column's color, use the data colors option in the Format tab.'); 
    } 

}

注意事项和限制

  • 某些错误和警告不是由视觉对象引起的。 例如，“值太多。未显示所有数据”错误源自 Power BI 服务。 此类错误和警告会在视觉对象的调用之前完成传播。 它们优先于源自视觉对象代码的错误。 如果在加载数据时出现错误，则在运行视觉对象的代码并满足显示警告图标条件之前，视觉对象将显示该错误，而不是显示警告图标错误。

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

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

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

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

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

  • 文本仅显示为纯文本

相关内容

DataViewUtils