Power BI ビジュアルでイベントを "レンダリング" する

  • [アーティクル]

認定済みのビジュアルを取得するには、そこにレンダリング イベントが含まれている必要があります。 これらのイベントを使用すると、ビジュアルがレンダリングされたタイミングと、エクスポートの準備が完了したタイミングがユーザー (基本的に、"PDF へのエクスポート" と "PowerPoint へのエクスポート" を行うユーザー) に知らされます。

重要

データを (PowerPoint や .pdf ファイルなどに) エクスポートするビジュアルには、レンダリングが完了する前にエクスポートが開始されないように、レンダリング イベントが含まれている必要があります。

レンダリング イベント API は、レンダリング中に呼び出しが必要な 3 つのメソッドで構成されています。

  • renderingStarted: Power BI ビジュアルのコードによって renderingStarted メソッドが呼び出され、レンダリング プロセスが開始したことを示します。 このメソッドからレンダリング プロセスが開始するため、このメソッドは常に "更新" メソッドの最初の行である必要があります。

  • 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. IVisual クラスの constructor メソッド内は、次のとおりです

    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 ビジュアルを取得する