通过

Power BI 视觉对象系统集成

  • 项目

本文介绍视觉对象 API，以及 Power BI 如何处理你、视觉对象和主机之间的交互。

可以手动或自动启动 Power BI 中的操作和后续更新。 更新类型：

下图显示了如何在 Power BI 中处理常见的基于视觉对象的操作，比如选择书签。

Power BI 视觉对象过程的示意图。

通过 Power BI 与视觉对象交互

可以使用 Power BI 更新视觉对象，如下所示：

  • 打开视觉对象的属性面板。

    当你打开视觉对象的属性面板时，Power BI 将从视觉对象的 capabilities.json 文件中获取支持的对象和属性。 若要接收属性的实际值，Power BI 调用视觉对象的 getFormattingModel 方法（而版本 5.0 之前的 API 调用 enumerateObjectInstances）。 API 返回新式格式窗格模型组件、属性及其实际值。

    有关详细信息，请参阅 Power BI 视觉对象的功能和属性。

  • 自定义可视化效果的标题、背景、标签和图例。

    当你在“格式”面板中更改属性的值时，Power BI 将调用 update 方法。 Power BI 将新的 options 对象传递给 update 方法，这些对象包含新值。

    有关详细信息，请参阅 Power BI 视觉对象的对象和属性。

  • 调整视觉对象的大小。

    当你更改视觉对象的大小时，Power BI 会调用 update 方法并传入新的 options 对象。 options 对象具有嵌套的 viewport 对象，这些对象包含视觉对象的新宽度和高度。

  • 应用报表、页面或视觉对象级筛选器。

    Power BI 根据筛选条件筛选数据。 Power BI 调用视觉对象的 update 方法，以通过新数据更新视觉对象。

    当其中一个嵌套对象中有新数据，视觉对象将获取 options 对象的新更新。 更新发生的方式取决于视觉对象的数据视图映射配置。

    有关详细信息，请参阅了解 Power BI 视觉对象中的数据视图映射。

  • 选择报表的另一个视觉对象中的数据点。

    当你在报表中选择另一个视觉对象中的数据点时，Power BI 将筛选或突出显示所选数据点并调用视觉对象的 update 方法。 视觉对象通过突出显示的数组获取新的筛选数据或相同数据。

    有关详细信息，请参阅突出显示 Power BI 视觉对象中的数据点。

  • 选择报表“书签”面板中的书签。

    在“书签”面板中选择书签时，请执行以下任一操作：

    • Power BI 调用通过 registerOnSelectionCallback 方法传递和注册的函数。 回调函数获取相应书签的选择数组。

    • Power BI 使用 options 对象内的相应 filter 对象调用 update 方法。

      在这两种情况下，视觉对象都会根据收到的选择或 filter 对象更改其状态。

      有关书签和筛选器的详细信息，请参阅 Power BI 视觉对象中的可视筛选器 API。

直接与视觉对象互动

你还可以直接与视觉对象交互进行更新：

  • 将鼠标悬停在数据元素上。

    视觉对象可通过 Power BI 工具提示 API 来显示关于数据点的更多信息。 当你将鼠标悬停在某个可视元素上时，视觉对象可以处理该事件，并显示关联的工具提示元素的相关数据。 视觉对象可显示标准工具提示或报表页工具提示。

    有关详细信息，请参阅向 Power BI 视觉对象添加工具提示。

  • 更改视觉对象属性（例如，通过展开树），视觉对象将新状态保存在视觉对象属性中。

    视觉对象可以通过 Power BI API 保存属性值。 例如，当你与视觉对象交互且视觉对象需要保存或更新属性值时，视觉对象可以调用 persistProperties 方法。

  • 选择 URL。

    默认情况下，视觉对象不能直接打开 URL。 若要在新选项卡中打开 URL，视觉对象可以调用 launchUrl 方法，并将 URL 作为参数传递。

    有关详细信息，请参阅创建启动 URL。

  • 通过视觉对象应用筛选器。

    视觉对象可以调用 applyJsonFilter 方法，并传递条件来筛选其他视觉对象中的数据。 多个筛选器类型可用，包括基本筛选器、高级筛选器和元组筛选器。

    有关详细信息，请参阅 Power BI 视觉对象中的可视筛选器 API。

  • 选择视觉对象中的元素。

    有关 Power BI 视觉对象中的选择的详细信息，请参阅使用 Power BI 视觉对象选择为视觉对象添加交互性。

视觉对象与 Power BI 交互

有时，视觉对象会启动与 Power BI 主机的通信，无需你输入任何内容：

  • 视觉对象请求 Power BI 中的更多数据。

    视觉对象逐项处理数据。 fetchMoreData API 方法请求语义模型中的下一个数据片段。

    有关详细信息，请参阅从 Power BI 获取更多数据。

  • 将触发事件服务。

    Power BI 可以将报表导出为 PDF 或通过电子邮件发送报表（仅适用于经认证的视觉对象）。 若要通知 Power BI 呈现已完成，并且视觉对象已准备好以 PDF 或电子邮件的形式捕获，则视觉对象应调用呈现事件 API。

    有关详细信息，请参阅从 Power BI 导出报表到 PDF。

    若要了解有关事件服务的信息，请参阅在 Power BI 视觉对象中“呈现”事件。

相关内容

对创建可视化效果并将它们添加到 Microsoft AppSource 感兴趣吗？ 请参阅以下文章：