在 Power BI 视觉对象中“呈现”事件

若要使视觉对象获得认证,它必须包含呈现事件。 这些事件让侦听器(主要是“导出到 PDF”和“导出到 PowerPoint”)知道视觉对象何时呈现以及何时可以导出。

重要

任何导出数据(例如,导出到 PowerPoint 或 .pdf 文件)的视觉对象都必须包含呈现事件,以确保在视觉对象完成呈现后才开始导出。

呈现事件 API 包含三种方法,应在呈现过程中调用这些方法:

  • renderingStarted:Power BI 视觉对象代码调用 renderingStarted 方法以指示呈现进程已开始。 此方法应始终位于 update 方法的第一行,因为这是呈现过程的开始。

  • renderingFinished:成功完成呈现后,Power BI 视觉对象代码调用 renderingFinished 方法来通知侦听器视觉对象的图像已准备好导出。 此方法应是视觉对象更新时执行的最后一行代码。 它通常(但不总是)是 update 方法的最后一行。

  • renderingFailed:如果在呈现过程中出现问题,Power BI 视觉对象将无法成功呈现。 要通知侦听器呈现过程尚未完成,Power BI 视觉对象代码应调用 renderingFailed 方法。 此方法还提供可选字符串用于说明失败原因。

注意

呈现事件是视觉对象认证的必需元素。 如果没有呈现事件,合作伙伴中心将不会批准你的视觉对象进行发布。 有关详细信息,请参阅认证要求

如何使用呈现事件 API

若要调用呈现方法,首先需要从 IVisualEventService 导入这些方法。

  1. visual.ts 文件中包括以下行:

    import IVisualEventService = powerbi.extensibility.IVisualEventService;
    
  2. IVisual 类中包括以下行:

    private events: IVisualEventService;
    
  3. IVisual 类的 constructor 方法中

    this.events = options.host.eventService;
    

现在可以在 update 方法中适当地调用方法 this.events.renderingStarted(options);this.events.renderingFinished(options);this.events.renderingFailed(options);

示例 1:没有动画的视觉对象

下面是一个使用呈现事件 API 的简单视觉对象示例。

    export class Visual implements IVisual {
        ...
        private events: IVisualEventService;
        ...

        constructor(options: VisualConstructorOptions) {
            ...
            this.events = options.host.eventService;
            ...
        }

        public update(options: VisualUpdateOptions) {
            this.events.renderingStarted(options);
            ...
            this.events.renderingFinished(options);
        }

示例 2:具有动画的视觉对象

如果视觉对象具有用于呈现的动画或异步函数,则应在动画之后或异步函数内部调用 renderingFinished 方法,即使它不是 update 方法的最后一行。

    export class Visual implements IVisual {
        ...
        private events: IVisualEventService;
        private element: HTMLElement;
        ...

        constructor(options: VisualConstructorOptions) {
            ...
            this.events = options.host.eventService;
            this.element = options.element;
            ...
        }

        public update(options: VisualUpdateOptions) {
            this.events.renderingStarted(options);
            ...
            // Learn more at https://github.com/d3/d3-transition/blob/master/README.md#transition_end
            d3.select(this.element).transition().duration(100).style("opacity","0").end().then(() => {
                // renderingFinished called after transition end
                this.events.renderingFinished(options);
            });
        }