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.

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 para chamar durante a renderização:

  • renderingStarted: chame esse método para indicar que a renderização foi iniciada. Sempre chame esse método como a primeira linha do método de atualização, já que é aí que o processo de renderização começa.

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

  • renderingFailed: chame esse método se ocorrer um problema durante a renderização, para notificar os ouvintes de que a renderização não foi concluída. Você pode passar uma cadeia de caracteres opcional para fornecer 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 importe o IVisualEventService tipo.

  1. visual.ts No arquivo, adicione a seguinte importação:

    import IVisualEventService = powerbi.extensibility.IVisualEventService;

  2. IVisual Na classe, adicione um campo privado:

    private events: IVisualEventService;

  3. constructor No método da IVisual classe, inicialize o campo:

    this.events = options.host.eventService;

Agora você pode chamar this.events.renderingStarted(options);, this.events.renderingFinished(options);e this.events.renderingFailed(options); quando apropriado em seu método de atualização .

Ciclo de vida do evento de renderização

Siga estas regras em todos os update() ciclos:

  1. Chame renderingStarted quando a renderização começar.
  2. Chame exatamente um método de conclusão para esse ciclo:
    • renderingFinished quando a renderização for bem-sucedida ou
    • renderingFailed quando a renderização falha.
  3. Para renderização assíncrona, a chamada renderingFinished somente após a renderização é realmente concluída.

Importante

Não deixe o update() método sair sem a conclusão da sinalização. Depois de ligar renderingStarted, você deve sempre ligar renderingFinished ou renderingFailed.

Padrões de implementação de código

Atualização síncrona com tratamento de falhas

public update(options: VisualUpdateOptions): void {
  this.host.eventService.renderingStarted(options);

  try {
    this.renderView(options); // visual rendering logic
    this.host.eventService.renderingFinished(options);
  } catch (error) {
    this.host.eventService.renderingFailed(options, String(error));
    throw error;
  }
}

Atualização assíncrona com tratamento de falhas

public async update(options: VisualUpdateOptions): Promise<void> {
  this.host.eventService.renderingStarted(options);

  try {
    await this.renderAsync(options); // visual rendering logic
    this.host.eventService.renderingFinished(options);
  } catch (error) {
    this.host.eventService.renderingFailed(options, String(error));
    throw error;
  }
}

Cadeia de promessas com .then().catch()

public update(options: VisualUpdateOptions): void {
  this.host.eventService.renderingStarted(options);

  this.renderAsync(options) // visual rendering logic
    .then(() => {
      this.host.eventService.renderingFinished(options);
    })
    .catch((error) => {
      this.host.eventService.renderingFailed(options, String(error));
      throw error;
    });
}

Conteúdo relacionado

  • Last updated on