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 匯入它們。
在您的
visual.ts
檔案中,包含這一行:import IVisualEventService = powerbi.extensibility.IVisualEventService;
在
IVisual
類別中包含這一行:private events: IVisualEventService;
在
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);
});
}