Eseguire il rendering degli eventi negli oggetti visivi di Power BIRender events in Power BI visuals

La nuova API è costituita da tre metodi (started, finished o failed) che devono essere chiamati durante il rendering.The new API consists of three methods (started, finished, or failed) that should be called during rendering.

All'avvio del rendering, il codice dell'oggetto visivo di Power BI chiama il metodo renderingStarted per indicare che il processo di rendering è stato avviato.When rendering starts, the Power BI visual code calls the renderingStarted method to indicate that the rendering process has started.

Se il rendering viene completato correttamente, il codice dell'oggetto visivo di Power BI chiama immediatamente il metodo renderingFinished, indicando ai listener (principalmente Esporta in PDF ed Esporta in PowerPoint) che l'immagine dell'oggetto visivo è pronta.If rendering is completed successfully, the Power BI visual code immediately calls the renderingFinished method, notifying the listeners (primarily, export to PDF and export to PowerPoint) that the visual's image is ready for export.

Se si verifica un problema durante il processo, il rendering dell'oggetto visivo Power BI non può essere eseguito correttamente.If a problem occurs during the process, the Power BI visual is prevented from being rendered successfully. Per segnalare ai listener che il processo di rendering non è stato completato, il codice dell'oggetto visivo di Power BI deve chiamare il metodo renderingFailed.To notify the listeners that the rendering process hasn't been completed, the Power BI visual code should call the renderingFailed method. Questo metodo include anche una stringa facoltativa per indicare la causa dell'errore.This method also provides an optional string to provide a reason for the failure.

UtilizzoUsage

export interface IVisualHost extends extensibility.IVisualHost {
    eventService: IVisualEventService ;
}

/**
 * An interface for reporting rendering events
 */
export interface IVisualEventService {
    /**
     * Should be called just before the actual rendering starts, 
     * usually at the start of the update method
     *
     * @param options - the visual update options received as an update parameter
     */
    renderingStarted(options: VisualUpdateOptions): void;

    /**
     * Should be called immediately after rendering finishes successfully
     * 
     * @param options - the visual update options received as an update parameter
     */
    renderingFinished(options: VisualUpdateOptions): void;

    /**
     * Called when rendering fails, with an optional reason string
     * 
     * @param options - the visual update options received as an update parameter
     * @param reason - the optional failure reason string
     */
    renderingFailed(options: VisualUpdateOptions, reason?: string): void;
}

Esempio: l'oggetto visivo non visualizza animazioniSample: The visual displays no animations

    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: l'oggetto visivo visualizza le animazioniSample: The visual displays animations

Se l'oggetto visivo include animazioni o funzioni asincrone per il rendering, il metodo renderingFinished deve essere chiamato dopo l'animazione o all'interno della funzione asincrona.If the visual has animations or async functions for rendering, the renderingFinished method should be called after the animation or inside async function.

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

Eventi di rendering per la certificazione degli oggetti visiviRendering events for visual certification

Il supporto degli eventi di rendering da parte dell'oggetto visivo è uno dei requisiti per la certificazione degli oggetti visivi.One requirement of visuals certification is the support of rendering events by the visual. Per altre informazioni, vedere Requisiti di certificazione.For more information, see certification requirements.