„Rendering“-Ereignisse in Power BI-Visuals

Artikel
03/23/2023

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.

Wichtig

Alle Visuals, die Daten exportieren – z. B. in eine PowerPoint- oder .pdf-Datei – müssen Renderingereignisse enthalten, damit der Export nicht beginnt, bevor das Rendern des Visuals abgeschlossen ist.

Die API für Renderingereignisse besteht aus drei Methoden, die während dem Rendering aufgerufen werden sollten:

renderingStarted: Der Code des Power BI-Visuals ruft die renderingStarted-Methode auf, um mitzuteilen, dass der Renderingprozess begonnen hat. Diese Methode sollte immer die erste Zeile der update-Methode sein, da an dieser Stelle der Renderingprozess beginnt.
renderingFinished: Wenn das Rendering erfolgreich abgeschlossen ist, wird im Code des Power BI-Visuals die renderingFinished-Methode aufgerufen, um den Listenern mitzuteilen, dass das Image des Visuals bereit für den Export ist. Diese Methode sollte die letzte Codezeile sein, die ausgeführt wird, wenn das Visual aktualisiert wird. Sie ist in der Regel (aber nicht immer) die letzte Zeile der update-Methode.
renderingFailed: Wenn während des Renderingprozesses ein Problem auftritt, wird das Power BI-Visual nicht erfolgreich gerendert. Im Code des Power BI-Visuals muss die renderingFailed-Methode aufgerufen werden, durch die der Listener benachrichtigt wird, dass der Renderingvorgang noch nicht abgeschlossen wurde. Diese Methode stellt zusätzlich eine optionale Zeichenfolge zur Erläuterung der Fehlerursache bereit.

Hinweis

Renderingereignisse sind eine Voraussetzung für die Zertifizierung von Visuals. Ohne sie wird die Veröffentlichung Ihres Visual in Partner Center nicht genehmigt. Weitere Informationen finden Sie unter certification requirements (Zertifizierungsanforderungen).

Verwenden der API für Renderingereignisse

Damit Sie die Renderingmethoden aufrufen können, müssen Sie sie zuerst aus IVisualEventService importieren.

Fügen Sie in Ihrer Datei visual.ts die folgende Zeile ein:

import IVisualEventService = powerbi.extensibility.IVisualEventService;

Fügen Sie in der Klasse IVisual die folgende Zeile ein:
```
private events: IVisualEventService;
```
Fügen Sie in der constructor-Methode der IVisual-Klasse die folgende Zeile ein:
```
this.events = options.host.eventService;
```

Nun können Sie die Methoden this.events.renderingStarted(options);, this.events.renderingFinished(options); und ggf. this.events.renderingFailed(options); in Ihrer update-Methode aufrufen.

Beispiel 1: Visual ohne Animationen

Hier sehen Sie ein Beispiel für ein einfaches Visual, das die API für Renderingereignisse verwendet.

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

Beispiel 2: Visual mit Animationen

Wenn das Visual Animationen oder asynchrone Funktionen zum Rendern enthält, sollte die renderingFinished-Methode nach der Animation oder innerhalb der asynchronen Funktion aufgerufen werden, auch wenn es sich nicht um die letzte Zeile der update-Methode handelt.

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

Nächste Schritte

Visual-API

So lassen Sie sich ein Power BI-Visual zertifizieren