Eventos de "representación" en objetos visuales de Power BI

Artículo
03/23/2023

Para certificar un objeto visual, debe incluir eventos de representación. Estos eventos permiten que los clientes de escucha (principalmente exportar a PDF y exportar a PowerPoint) sepan cuándo se representa el objeto visual y cuándo está listo para exportarse.

Importante

Cualquier objeto visual que exporte datos (por ejemplo, a un archivo de PowerPoint o .pdf) debe contener eventos de representación para asegurarse de que la exportación no comienza antes de que el objeto visual termine de representarse.

La API de representación de eventos consta de tres métodos a los que se debe llamar durante la representación:

renderingStarted: el código del objeto visual de Power BI llama al método renderingStarted para indicar que se ha iniciado el proceso de representación. Este método siempre debe ser la primera línea del método update, ya que ahí es donde comienza el proceso de representación.
renderingFinished: cuando la representación se completa correctamente, el código del objeto visual de Power BI llama al método renderingFinished para notificar a los clientes de escucha que la imagen del objeto visual está lista para exportarse. Este método debe ser la última línea de código ejecutada cuando se actualiza el objeto visual. Suele ser la última línea del método de actualización, pero no siempre.
renderingFailed: si se produce un problema durante el proceso de representación, el objeto visual de Power BI no se representa correctamente. Para notificar a los clientes de escucha que el proceso de representación no se ha completado, el código del objeto visual de Power BI debe llamar al método renderingFailed. Este método también proporciona una cadena opcional para proporcionar un motivo del error.

Nota

Los eventos de representación son un requisito para la certificación de objetos visuales. Sin ellos, el Centro de partners no aprobará el objeto visual para su publicación. Para obtener más información, consulte Requisitos de certificación.

Procedimiento para usar la API de eventos de representación

Para llamar a los métodos de representación, primero debe importarlos desde IVisualEventService.

En el archivo visual.ts, incluya la línea siguiente:

import IVisualEventService = powerbi.extensibility.IVisualEventService;

En la clase IVisual, incluya la línea siguiente:
```
private events: IVisualEventService;
```

En el método constructor de la clase IVisual

this.events = options.host.eventService;

Ahora puede llamar a los métodos this.events.renderingStarted(options);, this.events.renderingFinished(options); y this.events.renderingFailed(options); cuando corresponda en el método update.

Ejemplo 1: Objeto visual sin animaciones

Este es un ejemplo de un objeto visual simple que usa la API de eventos de representación.

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

Ejemplo 2: Objeto visual con animaciones

Si el objeto visual tiene animaciones o funciones asincrónicas para la representación, se debe llamar al método renderingFinished después de la animación o dentro de la función asincrónica, incluso si no es la última línea del método 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);
            });
        }

Pasos siguientes

API de objeto visual

Obtención de un objeto visual de Power BI certificado