共用方式為

視覺效果 API

  • 發行項

所有視覺效果均以實作 IVisual 介面的類別開始。 您可以將該類別命名為任何想要的名稱，只要有一個實作 IVisual 介面的類別即可。

注意

視覺效果類別名稱必須與 pbiviz.json 檔案中的 visualClassName 相同。

視覺效果類別應實作以下方法，如下列範例所示：

  • constructor - 初始化視覺效果狀態的標準建構函式
  • update - 更新視覺效果的資料
  • getFormattingModel，會傳回一個填入屬性窗格 (格式化選項) 的格式化模型，您可以在其中視需要修改屬性
  • destroy - 用於清除的標準解構函式
class MyVisual implements IVisual {
    
    constructor(options: VisualConstructorOptions) {
        //one time setup code goes here (called once)
    }
    
    public update(options: VisualUpdateOptions): void {
        //code to update your visual goes here (called on all view or data changes)
    }

    public getFormattingModel(): FormattingModel {
        // returns modern format pane formatting model that contain all format pane components and properties (called on opening format and analytics pane or on editing format properties)
    }
    
    public destroy(): void {
        //one time cleanup code goes here (called once)
    }
}

建構函式

視覺效果類別的 constructor 會在視覺效果具現化時呼叫。 它可用於任何視覺效果所需的設定作業。

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

這些介面會隨著每個新的 API 版本更新。 如需最新的介面格式，請移至我們的 GitHub 存放庫。

下列清單描述 VisualConstructorOptions 介面的一些屬性：

  • element: HTMLElement - 包含您的視覺效果的 DOM 元素參考

  • host: IVisualHost - 可用於與視覺效果主機 (Power BI) 互動的屬性和服務集合

    IVisualHost 包含下列服務：

    • createSelectionIdBuilder - 產生並儲存視覺效果中可選取項目的中繼資料
    • createSelectionManager - 建立用於通知視覺效果主機有關選取項目狀態變更的通訊橋樑，請參閱選取項目 API。
    • hostCapabilities
    • refreshHostData
    • downloadService - 傳回下載的擴充結果資訊。
    • eventService - 傳回轉譯事件的相關資訊。
    • hostEnv
    • displayWarningIcon - 傳回錯誤或警告訊息。
    • licenseManager - 傳回授權資訊。
    • createLocalizationManager - 產生管理員以協助當地語系化
    • applyJsonFilter - 套用特定的篩選類型。 請參閱篩選 API
    • applyCustomSort - 允許自訂排序選項。
    • acquireAADTokenService - 傳回 Microsoft Entra ID 驗證資訊。
    • webAccessService - 傳回存取遠端資源的權限狀態。
    • openModalDialog - 傳回對話方塊。
    • persistProperties - 可讓使用者建立持久性設定並將其與視覺效果定義一起儲存，以便下次重新載入時可以使用
    • eventService - 傳回事件服務以支援轉譯事件
    • storageService - 傳回服務，以協助在視覺效果中使用本機儲存體
    • storageV2Service - 傳回服務，以協助在視覺效果中使用本機儲存體 (第 2 版)
    • tooltipService - 傳回工具提示服務，以協助在視覺效果中使用工具提示
    • telemetry
    • drill
    • launchUrl - 協助在下一個索引標籤中啟動 URL
    • authenticationService - 傳回 Microsoft Entra ID 權杖。
    • locale - 傳回地區設定字串，請參閱當地語系化
    • instanceId - 傳回用來識別目前視覺效果執行個體的字串
    • colorPalette - 傳回將色彩套用至資料所需的 colorPalette
    • fetchMoreData - 支援使用比標準限制 (1,000 個資料列) 更多的資料。 請參閱擷取更多資料
    • switchFocusModeState - 協助變更焦點模式狀態

update

所有視覺效果都必須實作公用更新方法，每當資料或主機環境發生變更時，就會加以呼叫。

public update(options: VisualUpdateOptions): void

VisualUpdateOptions

  • viewport: IViewport - 應在其中轉譯視覺效果的檢視區維度
  • dataViews: DataView[] - 包含呈現視覺效果所需的所有資料的資料檢視物件 (視覺效果通常會使用 DataView 下的分類屬性)
  • type: VisualUpdateType - 指示要更新之資料類型的旗標 ([資料] | [調整大小] | [ViewMode] | [樣式] | [ResizeEnd])
  • viewMode: ViewMode - 指示視覺效果檢視模式的旗標 ([檢視] | [編輯] | [InFocusEdit])
  • editMode: EditMode - 指示視覺效果編輯模式的旗標 ([預設] | [進階]) (如果視覺效果支援 AdvancedEditMode，則只有在將 editMode 設定為 [進階] 時，才應轉譯其進階 UI 控制項，請參閱 AdvancedEditMode)
  • operationKind?: VisualDataChangeOperationKind - 指示資料變更類型的旗標 ([建立] | [附加])
  • jsonFilters?: IFilter[] - 套用的 json 篩選條件集合
  • isInFocus?: boolean - 指示視覺效果是否處於焦點模式的旗標

getFormattingModel (選用)

每次我們開啟屬性窗格或使用者編輯窗格中的任何屬性時都會呼叫此方法一次。 它會傳回 FormattingModel，其中包含所有有關屬性窗格設計、階層、屬性和最新格式化值的資訊。

getFormattingModel(): visuals.FormattingModel;

destroy (選用)

卸載視覺效果時，會呼叫 destroy 函式，該函式可用於清除工作 (例如移除事件接聽程式)。

public destroy(): void

提示

Power BI 通常不會呼叫 destroy，因為移除包含視覺效果的整個 IFrame 會更快。

相關內容