시각적 개체 APIVisual API

모든 시각적 개체는 IVisual 인터페이스를 구현하는 클래스로 시작합니다.All visuals start with a class that implements the IVisual interface. IVisual 인터페이스를 구현하는 클래스가 정확히 하나만 있다면 클래스 이름은 무엇이든 지정할 수 있습니다.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)
    }
}

constructorconstructor

시각적 개체 클래스의 생성자는 시각적 개체를 인스턴스화할 때 호출됩니다.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 - 이벤트 서비스를 반환하여 렌더링 이벤트를 지원합니다.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 컨트롤을 렌더링해야 합니다. AdvancedEditMode를 참조하세요.)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

소멸 함수는 시각적 개체를 언로드할 때 호출되며 이벤트 수신기 제거와 같은 정리 작업에 사용될 수 있습니다.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는 일반적으로 destroy를 호출하지 않습니다. 시각적 개체를 포함하는 전체 IFrame을 제거하는 것이 더 빠르기 때문입니다.Power BI generally doesn't call destroy since it's faster to remove the entire IFrame that contains the visual.