共用方式為


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

若要取得視覺效果認證,它必須包含轉譯事件。 這些事件讓接聽程式 (主要是匯出至 PDF 和匯出至 PowerPoint) 知道視覺效果何時進行轉譯,以及何時準備好匯出。

重要

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

轉譯事件 API 是由應在轉譯期間呼叫的三個方法所組成:

  • renderingStarted:Power BI 視覺效果程式碼會呼叫 renderingStarted 方法來指出已啟動轉譯程序。 這個方法一律應該是 update 方法的第一行,,因為這是轉譯程序開始的地方。

  • renderingFinished:順利完成轉譯時,Power BI 視覺效果程式碼會呼叫 renderingFinished 方法,通知接聽程式已準備好匯出視覺效果的影像。 這個方法應該是視覺效果更新時執行的最後一行程式碼。 它通常是 update 方法的最後一行,但並非總是如此。

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

您現在可以在 update 方法中適當地呼叫 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:具有動畫的視覺效果

如果視覺效果具有動畫或非同步函式進行轉譯,則即使不是 update 方法的最後一行,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);
            });
        }