Görsel APIVisual API

Tüm görseller IVisual arabirimini uygulayan sınıfla başlar.All visuals start with a class that implements the IVisual interface. IVisual arabirimini uygulayan bir sınıf olduğu sürece, sınıfı dilediğiniz şekilde adlandırabilirsiniz.You can name the class anything as long as there's exactly one class that implements the IVisual interface.

Not

Görsel sınıfı adının pbiviz.json dosyasında tanımlananla eşleşmesi gerekir.The visual class name must match what's defined in the pbiviz.json file.

Uygulanması gereken aşağıdaki yöntemleri içeren örnek görsel sınıfına göz atın:See the sample visual class with the following methods that should be implemented:

  • constructor, görselin durumunu başlatmaya yönelik standart bir oluşturucuconstructor, a standard constructor to initialize the visual's state
  • update, görselin verilerini güncelleştirmek içinupdate, to update the visual's data
  • enumerateObjectInstances, nesneleri gerektiği şekilde düzenleyebileceğiniz özellik bölmesine (biçimlendirme seçenekleri), bu bölmeyi doldurmak amacıyla geri döndürmek içinenumerateObjectInstances, to return objects to populate the property pane (formatting options) where you can modify them as needed
  • destroy, temizleme için standart yıkıcı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)
    }
}

oluşturucuconstructor

Görsel sınıfının oluşturucusu, görsel somut hale geldiğinde çağrılır.The constructor of the visual class is called when the visual is instantiated. Görselin gereksinim duyduğu herhangi bir kurulum işlemi için kullanılabilir.It can be used for any set up operations needed by the visual.

constructor(options: VisualConstructorOptions)

VisualConstructorOptionsVisualConstructorOptions

  • element: HTMLElement, görselinizi içerecek DOM öğesine bir başvuruelement: HTMLElement, a reference to the DOM element that will contain your visual

  • host: IVisualHost, görsel ana bilgisayarıyla (Power BI) etkileşim kurmak için kullanılabilen özelliklerden ve hizmetlerden oluşan bir koleksiyonhost: IVisualHost, a collection of properties and services that can be used to interact with the visual host (Power BI)

    IVisualHost, şu hizmetleri içerir: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, görselinizdeki seçilebilir öğelerin meta verilerini oluşturup depolarcreateSelectionIdBuilder, generates and stores metadata for selectable items in your visual
    • createSelectionManager, seçim durumunda yapılan değişiklikleri görselin ana bilgisayarına bildirmek için kullanılan iletişim köprüsünü oluşturur, bkz. Seçim API’si.createSelectionManager, creates the communication bridge used to notify the visual's host on changes in the selection state, see Selection API.
    • createLocalizationManager, Yerelleştirme konusunda yardımcı olması için bir yönetici oluştururcreateLocalizationManager, generates a manager to help with Localization
    • allowInteractions: boolean, görselin etkileşimli olup olmaması gerektiğine yönelik ipucu veren boole bayrağıallowInteractions: boolean, a boolean flag which hints whether or not the visual should be interactive
    • applyJsonFilter, belirli filtre türlerini uygular, bkz. Filtre API’siapplyJsonFilter, applies specific filter types, see Filter API
    • persistProperties, kullanıcıların özellikleri kalıcı hale getirmesini ve görsel tanımıyla birlikte kaydetmesini sağlar, böylece sonraki yeniden yüklemede kullanılabilir hale getirirpersistProperties, allows users to persist properties and save them along with the visual definition, so they're available on the next reload
    • eventService, İşleme olaylarını desteklemek için bir olay hizmeti döndürüreventService, returns an event service to support Render events
    • storageService, görselde yerel depolama kullanmaya yardımcı olması için bir hizmet döndürürstorageService, returns a service to help use local storage in the visual
    • authenticationService, kullanıcı kimlik doğrulaması konusunda yardımcı olması için bir hizmet oluştururauthenticationService, generates a service to help with user authentication
    • tooltipService, görselde araç ipuçlarını kullanmaya yardımcı olması için bir araç ipucu hizmeti döndürürtooltipService, returns a tooltip service to help use tooltips in the visual
    • launchUrl, sonraki sekmede URL’yi başlatmaya yardımcı olurlaunchUrl, helps to launch URL in next tab
    • locale, bir yerel ayar dizesi döndürür, bkz. Yerelleştirmelocale, returns a locale string, see Localization
    • instanceId, geçerli görsel örneğini tanımlamak için bir dize döndürürinstanceId, returns a string to identify the current visual instance
    • colorPalette, verilerinize renk uygulamak için gereken colorPalette değerini döndürürcolorPalette, returns the colorPalette required to apply colors to your data
    • fetchMoreData, standart sınırdan (1.000 satır) daha fazla veri kullanmayı desteklerfetchMoreData, supports using more data than the standard limit (1K rows)
    • switchFocusModeState, odak modu durumunu değiştirmeye yardımcı olurswitchFocusModeState, helps to change the focus mode state

updateupdate

Tüm görsellerin verilerde veya ana bilgisayar ortamında bir değişiklik olduğunda çağrılan bir genel güncelleştirme yöntemi uygulaması gerekir.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, görselin içinde işlenmesi gereken görünüm penceresinin boyutlarıviewport: IViewport, dimensions of the viewport that the visual should be rendered within
  • dataViews: DataView[], görselinizi işlemek için gereken tüm verileri içeren bir görünüm penceresi nesnesi (görseliniz genellikle DataView bölümündeki kategorik özelliği kullanır)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, bu güncelleştirmenin türlerini belirten bayraklar (Data | Resize | ViewMode | Style | ResizeEnd)type: VisualUpdateType, flags to indicate the type(s) of this update (Data | Resize | ViewMode | Style | ResizeEnd)
  • viewMode: ViewMode, görselin görünüm modunu belirten bayraklar (View | Edit | InFocusEdit)viewMode: ViewMode, flags to indicate the view mode of the visual (View | Edit | InFocusEdit)
  • editMode: EditMode, görselin düzenleme modunu belirten bayrak (Default | Advanced) (görsel AdvancedEditMode’u destekliyorsa editMode Advanced olarak ayarlandığında gelişmiş kullanıcı arabirimi denetimlerini işlemesi gerekir, bkz. 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, veri değişikliğinin türünü belirten bayrak (Create | Append)operationKind?: VisualDataChangeOperationKind, flag to indicate type of data change (Create | Append)
  • jsonFilters?: IFilter[], uygulanan JSON filtreleri koleksiyonujsonFilters?: IFilter[], collection of applied json filters
  • isInFocus?: boolean, görselin odak modunda olup olmadığını belirten bayrakisInFocus?: boolean, flag to indicate if the visual is in focus mode or not

enumerateObjectInstances optionalenumerateObjectInstances optional

Bu yöntem, özelliklerde listelenen her nesne için çağrılır.This method is called for every object listed in the capabilities. Seçenekleri (şu anda sadece ad) kullanarak, bu özelliğin nasıl görüntüleneceği hakkında bilgi içeren bir VisualObjectInstanceEnumeration döndürürsünüz.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, nesnenin adıobjectName: string, name of the object

optional öğesini yok etmedestroy optional

Yok etme işlevi, görselinizin yükü kaldırıldığında çağrılır ve olay dinleyicilerini kaldırma gibi temizleme görevlerinde kullanılabilir.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

Not

Görseli içeren IFrame’i tamamen kaldırmak daha hızlı olduğundan, Power BI genellikle destroy öğesini çağırmaz.Power BI generally doesn't call destroy since it's faster to remove the entire IFrame that contains the visual.