如何处理事件

提示

在 power BI Embedded Analytics Playground的 开发人员沙盒 部分中,使用你自己的报表或示例报表实时试验 API。

事件用于在 Power BI 组件(例如报表)和 Web 应用程序代码之间进行通信。

嵌入组件在组件内执行操作后发出事件。 这些可以是用户交互,也可以是组件中的自动操作(如正在呈现的视觉对象)。

例如,当用户单击报表中的按钮时,buttonClicked 是由 Power BI 报表发出的事件。 可以使用 report.on(...)侦听事件,然后设置事件处理程序。

有关如何处理事件的示例

此示例演示如何处理报表事件。 若要了解其他类型的事件,请参阅 事件及其响应值

注意

使用 API 之前,请等待组件加载。 侦听加载的事件,然后发出新命令。

report.on('loaded', function(event)
{
    reportPages = await report.getPages();
});

如何删除事件处理程序

可以使用 report.off(...) 删除特定事件的所有事件处理程序。

事件及其响应值

查看可能事件及其响应值的完整列表。

错误事件(与所有嵌入相关)

发出错误事件来描述失败的操作。

interface IError {
    message: string // A general message that describes the operation that failed (example: "Could not set page")
    detailedMessage?: string // Detailed message that describes the error
    errorCode?: string  //  Short message that describes the error
    level?: TraceType // The level of the error (example: 'Fatal')
    technicalDetails?: ITechnicalDetails
}

interface ITechnicalDetails {
    requestId?: string // Id for debugging - should be provided when reporting a bug
}

注意

只有 message 属性是必需的,其他属性可能未定义。

报告事件

发出报表事件以与嵌入报表交互,例如单击报表按钮或呈现视觉对象。

buttonClicked

当用户单击 报表 按钮时,将引发 buttonClicked 事件。

 id: string
 title?: string
 type?: string (type of button)
 bookmark?: string

commandTriggered

当用户单击 扩展命令时,将引发 commandTriggered 事件。

 command: string
 dataPoints?: IIdentityValue[]
 report: models.IReport
 page: models.IPage
 visual: models.IVisual

dataHyperlinkClicked

单击超链接时将引发 dataHyperlinkClicked 事件,超链接的行为 设置为 NavigateAndRaiseEventRaiseEvent

 url: string
 report: models.IReport
 page: models.IPage
 visual: models.IVisual

有关详细信息,请参阅 配置报表设置

dataSelected

选择特定数据点时,将引发 dataSelected 事件。

 report: models.IReport
 page: models.IPage
 visual: models.IVisual
 filters: IFilter[]
 dataPoints: IIdentityValue[]

加载

当报表初始化时,将引发 loaded 事件。 Power BI 徽标消失时,加载已完成。

pageChanged

每当更改页面时,将引发 pageChanged 事件。

 newPage: Models.IPage

呈现

当完全呈现报表时,将引发 rendered 事件。 例如,如果在加载报表或用户交互后呈现所有视觉对象。

saveAsTriggered

当用户在 UI 中单击 另存为 时,将引发 saveAsTriggered 事件。 这样,便可以为 另存为 操作创建自己的对话框。

保存

当通过 UI 中的 savesaveAs 操作或使用 API 触发保存时,将引发 saved 事件。

selectionChanged

每当用户更改所选视觉对象时,将引发 selectionChanged 事件。 选择多个视觉对象时,selectedItems 是所有选定视觉对象的列表。

 report: models.IReport
 page: models.IPage
 visual?: models.IVisual
 selectedItems?: models.IVisual[]

visualClicked

每次单击视觉对象时都会引发 visualClicked 事件。

 report: models.IReport
 page: models.IPage
 visual: models.IVisual

visualRendered

呈现视觉对象时,将引发 visualRendered 事件(需要在设置对象中将 visualRenderedEvents 设置为 true)。

注意

由于视觉对象可能因用户交互而呈现,因此建议仅在需要时打开此事件。

 name: string

有关详细信息,请参阅 配置报表设置

报表嵌入移动事件

发出报表嵌入移动事件以与移动布局中的嵌入报表交互,例如轻扫的开始或结尾。

swipeStart 和 swipeEnd 事件

当用户开始或结束嵌入报表上的轻扫移动时,将引发 swipeStartswipeEnd 事件。

interface ISwipeEvent {
    currentPosition: IPosition
    startPosition: IPosition
}

interface IPosition {
    x: number
    y: number
}

仪表板事件

加载仪表板时以及用户单击仪表板中的磁贴时,将发出仪表板事件。

加载

当仪表板初始化时,将引发 loaded 事件。

tileClicked

当最终用户单击磁贴时,将引发 tileClicked 事件。 对于固定的实时页面,它不会引发。

 tileId: string
 navigationUrl: string
 pageName: string
 reportEmbedUrl: string

Q&A 事件

在输入问题后呈现视觉对象时,将引发问答(Q&A) 事件。

visualRendered (Q&A)

输入问题后呈现视觉对象并显示答案时,将引发 visualRendered 事件。

 question: string
 normalizedQuestion: string

磁贴事件

当用户单击磁贴时,将引发磁贴事件。

tileClicked (磁贴事件)

当最终用户单击磁贴时,将引发 tileClicked 事件。 对于固定的实时页面,它不会引发。

 tileId: string
 navigationUrl: string
 pageName: string
 reportEmbedUrl: string

tileLoaded

磁贴初始化时将引发 tileLoaded 事件。 Power BI 徽标消失时,加载已完成。