Eventi di "rendering" negli oggetti visivi di Power BI

Per ottenere un oggetto visivo certificato, questo deve includere eventi di rendering. Questi eventi consentono ai listener (principalmente: esportare in PDF ed esportare in PowerPoint) di sapere quando viene eseguito il rendering dell'oggetto visivo e quando è pronto per l'esportazione.

L'API eventi di rendering è costituita da tre metodi che devono essere chiamati durante il rendering:

• renderingStarted: il codice visivo di Power BI chiama il metodo renderingStarted per indicare che il processo di rendering è stato avviato. Questo metodo deve essere sempre la prima riga del metodo di aggiornamento , perché questa è la posizione in cui inizia il processo di rendering.

• renderingFinished: quando il rendering viene completato correttamente, il codice dell’oggetto visivo di Power BI chiama il metodo renderingFinished per notificare ai listener che l'immagine dell'oggetto visivo è pronta per l'esportazione. Questo metodo deve essere l'ultima riga di codice eseguita quando l'oggetto visivo viene aggiornato. In genere, ma non sempre, è l'ultima riga del metodo di aggiornamento.

• renderingFailed: se si verifica un problema durante il processo di rendering, il rendering dell'oggetto visivo di Power BI non viene eseguito correttamente. Per segnalare ai listener il mancato completamento del processo di rendering, il codice dell'oggetto visivo di Power BI deve chiamare il metodo renderingFailed. Questo metodo include anche una stringa facoltativa per indicare la causa dell'errore.

Come usare l'API degli eventi di rendering

Per chiamare i metodi di rendering, è necessario prima importarli da IVisualEventService.

1. Nel file visual.ts includere la riga:

   import IVisualEventService = powerbi.extensibility.IVisualEventService;
   

2. Nella classe IVisual includere la riga:

   private events: IVisualEventService;
   

3. Nel metodo constructor della classe IVisual

   this.events = options.host.eventService;
   

È ora possibile chiamare i metodi this.events.renderingStarted(options);, this.events.renderingFinished(options); e this.events.renderingFailed(options);, dove appropriato nel metodo di aggiornamento.

Esempio 1: oggetto visivo senza animazioni

Ecco un esempio di oggetto visivo semplice che usa l'API eventi di rendering.

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

Esempio 2: oggetto visivo con animazioni

Se l'oggetto visivo ha animazioni o funzioni asincrone per il rendering, il metodo renderingFinished deve essere chiamato dopo l'animazione o all'interno della funzione asincrona, anche se non è l'ultima riga del metodo di aggiornamento.

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

Contenuto correlato

• API per gli oggetti visivi
• Ottenere un oggetto visivo Power BI certificato