События отрисовки в визуальных элементах Power BI

  • Статья

Чтобы получить визуальную сертификацию, она должна включать события отрисовки. Эти события позволяют прослушивателям (в первую очередь экспортировать в PDF и экспортировать в PowerPoint) знать, когда визуальный элемент отрисовывается и когда он готов к экспорту.

Важно!

Любой визуальный элемент, экспортируемый (например, в pdf-файл PowerPoint или PDF-файл ), должен содержать события отрисовки, чтобы убедиться, что экспорт не начинается до завершения визуализации.

API событий отрисовки состоит из трех методов, которые должны вызываться во время отрисовки:

  • renderingStarted: визуальный renderingStarted код Power BI вызывает метод, чтобы указать, что процесс отрисовки запущен. Этот метод всегда должен быть первой строкой метода обновления, так как начинается процесс отрисовки.

  • renderingFinished: при успешном выполнении отрисовки визуальный код Power BI вызывает renderingFinished метод для уведомления прослушивателей о готовности изображения визуального элемента к экспорту. Этот метод должен быть последней строкой кода, выполняемой при обновлении визуального элемента. Обычно это, но не всегда, последняя строка метода обновления.

  • renderingFailed: если проблема возникает во время отрисовки, визуальный элемент Power BI не отображается успешно. Чтобы уведомить прослушивателей о том, что процесс отрисовки не был завершен, визуальный код Power BI должен вызвать renderingFailed метод. Этот метод также предоставляет необязательную строку, чтобы указать причину сбоя.

Примечание.

События отрисовки являются обязательными для сертификации визуальных элементов. Без них визуальный элемент не будет утвержден Центром партнеров для публикации. Дополнительные сведения см. в разделе "Требования к сертификации".

Использование API событий отрисовки

Чтобы вызвать методы отрисовки, необходимо сначала импортировать их из IVisualEventService.

  1. visual.ts В файле добавьте строку:

    import IVisualEventService = powerbi.extensibility.IVisualEventService;

  2. IVisual В класс включайте строку:

    private events: IVisualEventService;

  3. В методе constructorIVisual класса

    this.events = options.host.eventService;

Теперь можно вызвать методы this.events.renderingStarted(options);this.events.renderingFinished(options);и this.events.renderingFailed(options); в случае необходимости в методе обновления.

Пример 1. Визуальный элемент без анимации

Ниже приведен пример простого визуального элемента, использующего API событий отрисовки .

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

Пример 2. Визуальный элемент с анимациями

Если визуальный элемент имеет анимации или асинхронные функции для отрисовки, renderingFinished метод должен вызываться после анимации или асинхронной функции, даже если она не является последней строкой метода обновления .

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

Связанный контент

Визуальный API

Получение сертифицированного визуального элемента Power BI