在 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);
            });
        }

后续步骤

视觉对象 API

获取 Power BI 视觉对象认证