分享方式：

Power BI 視覺效果中的「轉譯」事件

  • 文章

若要取得 經過認證的視覺效果，它必須包含 轉譯事件。 這些事件可讓接聽程式（主要是 導出至 PDF 並 匯出至 PowerPoint）知道視覺效果的轉譯時間，以及何時準備好導出。

重要

任何導出數據的視覺效果（例如，導出至 PowerPoint 或 .pdf檔案）都必須包含轉譯事件，以確保導出不會在視覺效果完成轉譯 之前開始。

轉 譯事件 API 包含三個應在轉譯期間呼叫的方法：

  • renderingStarted:P ower 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. 在 constructor 類別的方法中IVisual

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

相關內容