ビジュアル APIVisual API

すべてのビジュアルは、IVisual インターフェイスを実装するクラスから開始されます。All visuals start with a class that implements the IVisual interface. IVisual インターフェイスを実装するクラスが 1 つしかない場合は、クラスに任意の名前を指定できます。You can name the class anything as long as there's exactly one class that implements the IVisual interface.

注意

ビジュアル クラス名は、pbiviz.json ファイルで定義されているものと一致する必要があります。The visual class name must match what's defined in the pbiviz.json file.

実装する必要がある次のメソッドを含むサンプル ビジュアル クラスをご確認ください。See the sample visual class with the following methods that should be implemented:

  • constructor は、ビジュアルの状態を初期化するための標準コンストラクターですconstructor, a standard constructor to initialize the visual's state
  • update は、ビジュアルのデータを更新しますupdate, to update the visual's data
  • enumerateObjectInstances は、プロパティ ペイン (書式設定オプション) を設定するためのオブジェクトを返します。ここでは必要に応じてオプションを変更できますenumerateObjectInstances, to return objects to populate the property pane (formatting options) where you can modify them as needed
  • destroy は、クリーンアップ用の標準デストラクターですdestroy, a standard destructor for cleanup
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 enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
        //returns objects to populate the property pane (called for each object defined in capabilities)
    }
    
    public destroy(): void {
        //one time cleanup code goes here (called once)
    }
}

コンストラクターconstructor

ビジュアル クラスのコンストラクターは、ビジュアルがインスタンス化されると呼び出されます。The constructor of the visual class is called when the visual is instantiated. ビジュアルに必要なすべての設定操作に使用できます。It can be used for any set up operations needed by the visual.

constructor(options: VisualConstructorOptions)

VisualConstructorOptionsVisualConstructorOptions

  • element: HTMLElement は、ビジュアルを格納する DOM 要素への参照ですelement: HTMLElement, a reference to the DOM element that will contain your visual

  • host: IVisualHost は、ビジュアル ホスト (Power BI) との対話に使用できるプロパティとサービスのコレクションですhost: IVisualHost, a collection of properties and services that can be used to interact with the visual host (Power BI)

    IVisualHost には、次のサービスが含まれています。IVisualHost contains the following services:

    export interface IVisualHost extends extensibility.IVisualHost {
         createSelectionIdBuilder: () => visuals.ISelectionIdBuilder;
         : () => ISelectionManager;
         colorPalette: ISandboxExtendedColorPalette;
         persistProperties: (changes: VisualObjectInstancesToPersist) => void;
         applyJsonFilter: (filter: IFilter[] | IFilter, objectName: string, propertyName: string, action: FilterAction) => void;
         tooltipService: ITooltipService;
         telemetry: ITelemetryService;
         authenticationService: IAuthenticationService;
         locale: string;
         allowInteractions: boolean;
         launchUrl: (url: string) => void;
         fetchMoreData: () => boolean;
         instanceId: string;
         refreshHostData: () => void;
         createLocalizationManager: () => ILocalizationManager;
         storageService: ILocalVisualStorageService;
         eventService: IVisualEventService;
         switchFocusModeState: (on: boolean) => void;
    }
    
    • createSelectionIdBuilder は、ビジュアル内の選択可能な項目を表すメタデータを生成および格納しますcreateSelectionIdBuilder, generates and stores metadata for selectable items in your visual
    • createSelectionManager は、選択状態の変更について、ビジュアルのホストに通知を行うために使用される通信ブリッジを作成します。選択 API に関するページをご覧ください。createSelectionManager, creates the communication bridge used to notify the visual's host on changes in the selection state, see Selection API.
    • createLocalizationManager は、ローカライズを支援するマネージャーを生成しますcreateLocalizationManager, generates a manager to help with Localization
    • allowInteractions: boolean は、ビジュアルを対話形式にする必要があるかどうかのヒントを提供するブール型のフラグですallowInteractions: boolean, a boolean flag which hints whether or not the visual should be interactive
    • applyJsonFilter は、特定のフィルターの種類を適用します。フィルター API に関するページをご覧くださいapplyJsonFilter, applies specific filter types, see Filter API
    • persistProperties は、プロパティを保持し、ビジュアル定義と共に保存できるようにします。これによって、次回の再読み込み時にプロパティが利用可能になりますpersistProperties, allows users to persist properties and save them along with the visual definition, so they're available on the next reload
    • eventService は、Render イベントをサポートするイベント サービスを返しますeventService, returns an event service to support Render events
    • storageService は、ビジュアルでローカル ストレージを使用できるようにするためのサービスを返しますstorageService, returns a service to help use local storage in the visual
    • authenticationService は、ユーザー認証を支援するサービスを生成しますauthenticationService, generates a service to help with user authentication
    • tooltipService は、ビジュアルでツールヒントを使用できるようにするツールヒント サービスを返しますtooltipService, returns a tooltip service to help use tooltips in the visual
    • launchUrl は、次のタブで URL を起動する際に役立ちますlaunchUrl, helps to launch URL in next tab
    • locale は、ロケール文字列を返します。ローカライズに関するページをご覧くださいlocale, returns a locale string, see Localization
    • instanceId は、現在のビジュアル インスタンスを識別する文字列を返しますinstanceId, returns a string to identify the current visual instance
    • colorPalette は、データに色を適用するために必要な colorPalette を返しますcolorPalette, returns the colorPalette required to apply colors to your data
    • fetchMoreData は、標準の制限 (1,000 行) を超えるデータの使用をサポートしますfetchMoreData, supports using more data than the standard limit (1K rows)
    • switchFocusModeState は、フォーカス モードの状態を変更する際に役立ちますswitchFocusModeState, helps to change the focus mode state

updateupdate

すべてのビジュアルでは、データまたはホスト環境が変更されるたびに呼び出されるパブリック更新メソッドを実装する必要があります。All visuals must implement a public update method that's called whenever there's a change in the data or host environment.

public update(options: VisualUpdateOptions): void

VisualUpdateOptionsVisualUpdateOptions

  • viewport: IViewport は、ビジュアルがレンダリングされる必要があるビューポートのディメンションですviewport: IViewport, dimensions of the viewport that the visual should be rendered within
  • dataViews: DataView[] は、ビジュアルをレンダリングするために必要なすべてのデータを含む DataView オブジェクトです (ビジュアルは通常、DataView の下のカテゴリ プロパティを使用します)dataViews: DataView[], the dataview object which contains all data needed to render your visual (your visual will typically use the categorical property under DataView)
  • type: VisualUpdateType は、この更新の種類 (Data | Resize | ViewMode | Style | ResizeEnd) を示すフラグですtype: VisualUpdateType, flags to indicate the type(s) of this update (Data | Resize | ViewMode | Style | ResizeEnd)
  • viewMode: ViewMode は、ビジュアルのビュー モード (View | Edit | InFocusEdit) を示すフラグですviewMode: ViewMode, flags to indicate the view mode of the visual (View | Edit | InFocusEdit)
  • editMode: EditMode は、ビジュアルの編集モード (Default | Advanced) を示すフラグです (ビジュアルが AdvancedEditMode をサポートしている場合、editModeAdvanced に設定されているときのみ、高度な UI コントロールがレンダリングされます。高度な編集モードに関するページをご覧ください)editMode: EditMode, flag to indicate the edit mode of the visual (Default | Advanced) (if the visual supports AdvancedEditMode, it should render its advanced UI controls only when editMode is set to Advanced, see AdvancedEditMode)
  • operationKind?: VisualDataChangeOperationKind は、データ変更の種類 (Create | Append) を示すフラグですoperationKind?: VisualDataChangeOperationKind, flag to indicate type of data change (Create | Append)
  • jsonFilters?: IFilter[] は、適用される JSON フィルターのコレクションですjsonFilters?: IFilter[], collection of applied json filters
  • isInFocus?: boolean は、ビジュアルがフォーカス モードであるかどうかを示すフラグですisInFocus?: boolean, flag to indicate if the visual is in focus mode or not

enumerateObjectInstances optionalenumerateObjectInstances optional

このメソッドは、機能に示されているすべてのオブジェクトに対して呼び出されます。This method is called for every object listed in the capabilities. オプション (現在は名前のみ) を使用すると、このプロパティを表示する方法に関する情報を含む VisualObjectInstanceEnumeration が返されます。Using the options (currently just the name) you return a VisualObjectInstanceEnumeration with information about how to display this property.

enumerateObjectInstances(options:EnumerateVisualObjectInstancesOptions):VisualObjectInstanceEnumeration

EnumerateVisualObjectInstancesOptionsEnumerateVisualObjectInstancesOptions

  • objectName: string は、オブジェクトの名前ですobjectName: string, name of the object

destroy optionaldestroy optional

destroy 関数は、ビジュアルがアンロードされると呼び出され、イベント リスナーの削除などのクリーンアップ タスクに使用できます。The destroy function is called when your visual is unloaded and can be used for clean up tasks such as removing event listeners.

public destroy(): void

注意

Power BI では、ビジュアルを含む IFrame 全体を削除する方が簡単であるため、通常は destroy が呼び出されることはありません。Power BI generally doesn't call destroy since it's faster to remove the entire IFrame that contains the visual.