Eventi di "rendering" negli oggetti visivi di Power BI

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

Importante

Qualsiasi oggetto visivo che esporta dati (ad esempio, in un file PowerPoint o pdf ) deve contenere eventi di rendering per assicurarsi che l'esportazione non inizi prima del completamento del rendering dell'oggetto visivo.

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

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

• renderingFinished: quando il rendering viene completato correttamente, il codice visivo di Power BI chiama il renderingFinished metodo 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, l'oggetto visivo di Power BI non viene eseguito correttamente. Per notificare ai listener che il processo di rendering non è stato completato, il codice visivo di Power BI deve chiamare il renderingFailed metodo . Questo metodo fornisce anche una stringa facoltativa per fornire un motivo per l'errore.

Nota

Gli eventi di rendering sono un requisito per la certificazione degli oggetti visivi. Senza di essi l'oggetto visivo non verrà approvato dal Centro per i partner per la pubblicazione. Per altre informazioni, vedere Requisiti di certificazione.

Come usare l'API degli eventi di rendering

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

1. visual.ts Nel file includere la riga :

   import IVisualEventService = powerbi.extensibility.IVisualEventService;
   

2. IVisual Nella classe includere la riga :

   private events: IVisualEventService;
   

3. constructor Nel metodo della IVisual classe

   this.events = options.host.eventService;
   

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

Esempio 1: Oggetto visivo senza animazioni

Ecco un esempio di oggetto visivo semplice che usa l'API degli 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 renderingFinished metodo deve essere chiamato dopo l'animazione o all'interno della funzione asincrona, anche se non è l'ultima riga del metodo 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);
            });
        }

Contenuto correlato

API visiva

Ottenere un oggetto visivo certificato di Power BI