Vykreslování událostí ve vizuálech Power BIRender events in Power BI visuals

Nové rozhraní API je tvořeno třemi metodami (started, finished, failed), které je možné volat při vykreslování.The new API consists of three methods (started, finished, or failed) that should be called during rendering.

Při zahájení vykreslování kód vizuálu Power BI zavolá metodu renderingStarted, čímž indikuje, že proces vykreslování byl zahájen.When rendering starts, the Power BI visual code calls the renderingStarted method to indicate that the rendering process has started.

Pokud se vykreslení dokončí úspěšně, kód vizuálu Power BI okamžitě zavolá metodu renderingFinished, čímž naslouchacím procesům (primárně procesům exportu do PDF a exportu do PowerPointu) oznámí, že image vizuálu je připravena k exportu.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.

Pokud během daného procesu dojde k nějakému problému, vizuál Power BI se úspěšně nevykreslí.If a problem occurs during the process, the Power BI visual is prevented from being rendered successfully. Kód vizuálu Power BI by měl zavolat metodu renderingFailed, která naslouchacím procesům oznámí, že proces vykreslování se nedokončil.To notify the listeners that the rendering process hasn't been completed, the Power BI visual code should call the renderingFailed method. Tato metoda také poskytuje volitelný řetězec pro označení důvodu selhání.This method also provides an optional string to provide a reason for the failure.

VyužitíUsage

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

Ukázka: Vizuál nezobrazuje animace.Sample: 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);
        }

Ukázka: Vizuál zobrazuje animace.Sample: The visual displays animations

Pokud má vizuál animace nebo asynchronní funkce pro vykreslení, je třeba po animaci nebo uvnitř asynchronní funkce zavolat metodu renderingFinished.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);
            });
        }

Vykreslování událostí pro certifikaci vizuáluRendering events for visual certification

Jedním z požadavků na certifikaci vizuálů je podpora vykreslování událostí vizuálem.One requirement of visuals certification is the support of rendering events by the visual. Další informace najdete v požadavcích na certifikaci.For more information, see certification requirements.