Como "renderizar" eventos em visuais do Power BI

Para tornar um visual certificado, ele precisa incluir eventos de renderização. Esses eventos permitem que os ouvintes (principalmente, exportar para PDF e exportar para PowerPoint) saibam quando o visual está sendo renderizado e quando ele está pronto para exportação.

A API de eventos de renderização consiste em três métodos que devem ser chamados durante a renderização:

• renderingStarted: o código do visual do Power BI chama o método renderingStarted para indicar que o processo de renderização foi iniciado. Esse método sempre deve ser a primeira linha do método update, pois é aí que o processo de renderização começa.

• renderingFinished: quando a renderização for concluída com êxito, o código visual do Power BI chamará o método para notificar os ouvintes de que a imagem do visual renderingFinished está pronta para exportação. Esse método deve ser a última linha de código executada quando o visual é atualizado. Normalmente (mas nem sempre) ele é a última linha do método update.

• renderingFailed: se ocorrer um problema durante o processo de renderização, o visual do Power BI não será renderizado com êxito. Para notificar os ouvintes de que o processo de renderização não foi concluído, o código do visual do Power BI deve chamar o método renderingFailed. Esse método também fornece uma cadeia de caracteres opcional para informar um motivo para a falha.

Como usar a API de eventos de renderização

Para chamar os métodos de renderização, primeiro você precisa importá-los do IVisualEventService.

1. Em seu arquivo visual.ts, inclua a linha:

   import IVisualEventService = powerbi.extensibility.IVisualEventService;
   

2. Na classe IVisual, inclua a linha:

   private events: IVisualEventService;
   

3. No método constructor da classe IVisual

   this.events = options.host.eventService;
   

Agora você pode chamar os métodos this.events.renderingStarted(options);, this.events.renderingFinished(options); e this.events.renderingFailed(options); quando apropriado em seu método update.

Exemplo 1: visual sem animações

Aqui está um exemplo de um visual simples que usa a API de renderização de eventos.

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

Exemplo 2: visual sem animações

Se o visual tiver animações ou funções assíncronas para renderização, o método renderingFinished deverá ser chamado após a animação ou dentro da função assíncrona, mesmo que essa não seja a última linha do 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);
            });
        }

Conteúdo relacionado

• API do Visual
• Certificar um visual do Power BI