ビジュアル 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
が呼び出されることはありません。