Como "renderizar" eventos em visuais do Power BI

Artigo
03/23/2023

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.

Importante

Qualquer visual que exporte dados (por exemplo, para um arquivo do PowerPoint ou .pdf) deve conter eventos de renderização para garantir que a exportação não comece antes de a renderização do visual ser concluída.

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 visual deve chamar o método renderingFailed. Esse método também fornece uma cadeia de caracteres opcional para informar um motivo para a falha.

Observação

Os eventos de renderização são um requisito para a certificação de visuais. Sem eles, o seu visual não será aprovado pelo Partner Center para publicação. Para obter mais informações, confira requisitos de certificação.

Como usar a API de eventos de renderização

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

Em seu arquivo visual.ts, inclua a linha:

import IVisualEventService = powerbi.extensibility.IVisualEventService;

Na classe IVisual, inclua a linha:
```
private events: IVisualEventService;
```

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

Próximas etapas

API do Visual

Certificar um visual do Power BI