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

  • 發行項

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

重要

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

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

  • 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. 在 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);
            });
        }

相關內容

Visual API

取得 Power BI 視覺效果認證