ビジュアル API

  • [アーティクル]

すべてのビジュアルは、IVisual インターフェイスを実装するクラスから開始されます。 IVisual インターフェイスを実装するクラスが 1 つしかない場合は、クラスに任意の名前を指定できます。

注意

ビジュアル クラス名は、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 - 選択状態の変更について、ビジュアルのホストに通知を行うために使用される通信ブリッジが作成されます。Selection API に関するページをご覧ください。
    • hostCapabilities
    • refreshHostData
    • downloadService - ダウンロードの拡張された結果情報を返します。
    • eventService - レンダリング イベントに関する情報を返します。
    • hostEnv
    • displayWarningIcon - エラーまたは警告メッセージを返します。
    • licenseManager - ライセンス情報を返します。
    • createLocalizationManager - ローカライズを支援するマネージャーを生成します
    • applyJsonFilter - 特定のフィルターの種類を適用します。 フィルター API を参照してください
    • applyCustomSort - カスタム並べ替えオプションを許可します。
    • acquireAADTokenService - Microsoft Entra ID 認証情報を返します。
    • webAccessService - リモート リソースへのアクセスに関するアクセス許可の状態を返します。
    • openModalDialog - ダイアログ ボックスを返します。
    • persistProperties - 固定の設定を作成し、ビジュアル定義と共に保存できるようにします。これによって、次回の再読み込み時にこれが利用可能になります
    • eventService - Render イベントをサポートするイベント サービスを返します
    • 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 - 更新されるデータの種類 (Data | Resize | ViewMode | Style | ResizeEnd) を示すフラグです
  • viewMode: ViewMode - ビジュアルのビュー モード (View | Edit | InFocusEdit) を示すフラグです
  • editMode: EditMode - ビジュアルの編集モード (Default | Advanced) を示すフラグです (ビジュアルが AdvancedEditMode をサポートしている場合、editMode が Advanced に設定されているときのみ、高度な UI コントロールがレンダリングされます。AdvancedEditMode に関するページをご覧ください)
  • operationKind?: VisualDataChangeOperationKind - データ変更の種類 (Create | Append) を示すフラグです
  • jsonFilters?: IFilter[] - 適用される JSON フィルターのコレクションです
  • isInFocus?: boolean - ビジュアルがフォーカス モードであるかどうかを示すフラグです

getFormattingModel "(省略可能)"

このメソッドは、[プロパティ] ペインを開くたびに、またはユーザーがペイン内のプロパティを編集するたびに、一度だけ呼び出されます。 [プロパティ] ペインのデザイン、階層、プロパティ、最新の書式の値に関するすべての情報を含む FormattingModel を返します。

getFormattingModel(): visuals.FormattingModel;

destroy (省略可能)

destroy 関数は、ビジュアルがアンロードされると呼び出され、イベント リスナーの削除などのクリーンアップ タスクに使用できます。

public destroy(): void

ヒント

Power BI では、ビジュアルを含む IFrame 全体を削除する方が簡単であるため、通常は destroy が呼び出されることはありません。

関連するコンテンツ