„Rendering“-Ereignisse in Power BI-Visuals

Damit ein Visual zertifiziert werden kann, muss es Renderingereignisse umfassen. Diese Ereignisse teilen Listenern (vor allem In PDF exportieren und Nach PowerPoint exportieren) mit, wenn das Visual gerendert wird und wenn es bereit zum Exportieren ist.

Die Renderingereignisse-API besteht aus drei Methoden zum Aufrufen während des Renderings:

• renderingStarted: Rufen Sie diese Methode auf, um anzugeben, dass das Rendering gestartet wurde. Rufen Sie diese Methode immer als erste Zeile der Updatemethode auf, da dort der Renderingvorgang beginnt.

• renderingFinished: Rufen Sie diese Methode auf, wenn das Rendern erfolgreich abgeschlossen ist, um Listener zu benachrichtigen, dass das Bild des visuellen Elements für den Export bereit ist. Dieser Aufruf sollte die letzte Codezeile sein, die ausgeführt wird, wenn die visuelle Aktualisierung erfolgt. Sie ist in der Regel (aber nicht immer) die letzte Zeile der update-Methode.

• renderingFailed: Rufen Sie diese Methode auf, wenn während des Renderings ein Problem auftritt, um Listener darüber zu benachrichtigen, dass das Rendering nicht abgeschlossen wurde. Sie können eine optionale Zeichenfolge übergeben, um einen Grund für den Fehler anzugeben.

Verwenden der API für Renderingereignisse

Um die Renderingmethoden aufzurufen, importieren Sie zuerst den IVisualEventService Typ.

1. Fügen Sie in Ihrer visual.ts Datei den folgenden Import hinzu:

   import IVisualEventService = powerbi.extensibility.IVisualEventService;
   

2. Fügen Sie in der IVisual Klasse ein privates Feld hinzu:

   private events: IVisualEventService;
   

3. Initialisieren Sie in der constructor Methode der IVisual Klasse das Feld:

   this.events = options.host.eventService;
   

Sie können jetzt , this.events.renderingFinished(options);und this.events.renderingFailed(options); gegebenenfalls in Ihrer Update-Methode aufrufenthis.events.renderingStarted(options);.

Rendern des Ereignislebenszyklus

Befolgen Sie die folgenden Regeln in jedem update() Zyklus:

1. Aufruf renderingStarted beim Rendern beginnt.
2. Rufen Sie genau eine Abschlussmethode für diesen Zyklus auf:
   • renderingFinished wenn das Rendern erfolgreich ist, oder
   • renderingFailed wenn das Rendern fehlschlägt.
3. Rufen Sie renderingFinished für asynchrones Rendering nur nach Abschluss des Renderings auf.

Codeimplementierungsmuster

Synchrone Aktualisierung mit Fehlerbehandlung

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

Asynchrone Aktualisierung mit Fehlerbehandlung

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

Zusagekette mit .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;
    });
}

Zugehöriger Inhalt

• Visual-API
• So lassen Sie sich ein Power BI-Visual zertifizieren