Vizualizációs APIVisual API

Minden vizualizáció egy osztállyal kezdődik, amely implementálja az IVisual felületet.All visuals start with a class that implements the IVisual interface. Az osztálynak bármilyen nevet adhat, ha pontosan egy olyan osztály van, amely implementálja az IVisual felületet.You can name the class anything as long as there's exactly one class that implements the IVisual interface.

Megjegyzés

A vizualizációosztály nevének meg kell egyeznie a pbiviz.json fájlban megadott névvel.The visual class name must match what's defined in the pbiviz.json file.

Tekintse meg a minta vizualizációosztályt az alábbi implementálandó metódusokkal:See the sample visual class with the following methods that should be implemented:

  • constructor, egy standard konstruktor a vizualizáció állapotának inicializálásáhozconstructor, a standard constructor to initialize the visual's state
  • update a vizualizáció adatainak frissítéséhezupdate, to update the visual's data
  • enumerateObjectInstances, amely objektumokat ad vissza a tulajdonságpanel kitöltéséhez (formázási lehetőségek), ahol szükség szerint módosíthatókenumerateObjectInstances, to return objects to populate the property pane (formatting options) where you can modify them as needed
  • destroy, standard destruktor a tisztításhozdestroy, 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)
    }
}

konstruktorconstructor

A vizualizációs osztály konstruktorát a vizualizáció példányosításakor hívja meg a rendszer.The constructor of the visual class is called when the visual is instantiated. A vizualizáció számára szükséges bármilyen beállítási művelethez használható.It can be used for any set up operations needed by the visual.

constructor(options: VisualConstructorOptions)

VisualConstructorOptionsVisualConstructorOptions

  • element: HTMLElement, hivatkozás a DOM-elemre, amely tartalmazza a vizualizációtelement: HTMLElement, a reference to the DOM element that will contain your visual

  • host: IVisualHost, tulajdonságok és szolgáltatások gyűjteménye, amelyek a vizualizációs gazdagéppel (Power BI) való interakcióhoz használhatókhost: IVisualHost, a collection of properties and services that can be used to interact with the visual host (Power BI)

    Az IVisualHost az alábbi szolgáltatásokat tartalmazza: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, metaadatokat hoz létre és tárol a vizualizációban kiválasztható elemek számáracreateSelectionIdBuilder, generates and stores metadata for selectable items in your visual
    • createSelectionManager, létrehozza azt a kommunikációs hidat, amely értesíti a vizualizáció gazdagépét a kiválasztási állapot változásairól, lásd: Kiválasztási API.createSelectionManager, creates the communication bridge used to notify the visual's host on changes in the selection state, see Selection API.
    • createLocalizationManager, létrehoz egy kezelőt, amely a Honosítást segíticreateLocalizationManager, generates a manager to help with Localization
    • allowInteractions: boolean, egy logikai jelölő, amely azt jelzi, hogy a vizualizációnak interaktívnak kell-e lennieallowInteractions: boolean, a boolean flag which hints whether or not the visual should be interactive
    • applyJsonFilter, adott szűrőtípusokat alkalmaz, lásd: Szűrő APIapplyJsonFilter, applies specific filter types, see Filter API
    • persistProperties, lehetővé teszi a felhasználók számára, hogy megőrizzék és a vizualizáció definíciójával együtt mentsék a tulajdonságokat, hogy a következő újratöltéssel elérhetők legyenekpersistProperties, allows users to persist properties and save them along with the visual definition, so they're available on the next reload
    • eventService, visszaad egy eseményszolgáltatást a Renderelési események támogatásáhozeventService, returns an event service to support Render events
    • storageService, visszaad egy szolgáltatást, amely a helyi tárterület vizualizációban való használatát segítistorageService, returns a service to help use local storage in the visual
    • authenticationService, létrehoz egy szolgáltatást, amely a felhasználói hitelesítést segítiauthenticationService, generates a service to help with user authentication
    • tooltipService, visszaad egy elemleírási szolgáltatást, amely az elemleírások vizualizációban való használatát segítitooltipService, returns a tooltip service to help use tooltips in the visual
    • launchUrl, segít a következő lapon lévő URL elindításábanlaunchUrl, helps to launch URL in next tab
    • locale, visszaad egy területi beállítás típusú sztringet, lásd: Lokalizációlocale, returns a locale string, see Localization
    • instanceId, visszaad egy sztringet az aktuális vizualizációpéldány azonosításáhozinstanceId, returns a string to identify the current visual instance
    • colorPalette, visszaadja az adatok színbeállításához szükséges színpalettátcolorPalette, returns the colorPalette required to apply colors to your data
    • fetchMoreData, támogatja a standard határértéknél (ezer sor) nagyobb adatfelhasználástfetchMoreData, supports using more data than the standard limit (1K rows)
    • switchFocusModeState, segít módosítani a fókusz mód állapotátswitchFocusModeState, helps to change the focus mode state

updateupdate

Minden vizualizációnak implementálnia kell egy nyilvános frissítési metódust, amelyet az adatok vagy a gazdakörnyezet minden módosításakor meghív a rendszer.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, a vizualizáció renderelési mintájának méreteiviewport: IViewport, dimensions of the viewport that the visual should be rendered within
  • dataViews: DataView[], a DataView objektum, amely tartalmazza a vizualizáció megjelenítéséhez szükséges összes adatot (a vizualizáció általában a DataView alatt található kategorikus tulajdonságot fogja használni)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, a frissítés típusát/típusait jelző jelölő (Data | Resize | ViewMode | Style | ResizeEnd)type: VisualUpdateType, flags to indicate the type(s) of this update (Data | Resize | ViewMode | Style | ResizeEnd)
  • viewMode: ViewMode, a vizualizáció megtekintési módját jelölő jelző (View | Edit | InFocusEdit)viewMode: ViewMode, flags to indicate the view mode of the visual (View | Edit | InFocusEdit)
  • editMode: EditMode, a vizualizáció szerkesztési módját jelző jelölő (Default | Advanced) (ha a vizualizáció támogatja az AdvancedEditMode módot, csak akkor kell renderelnie a speciális felhasználói felületi vezérlőket, ha az editMode Advanced értékre van állítva, lásd: 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, jelölő az adatváltozás típusának jelzésére (Create | Append)operationKind?: VisualDataChangeOperationKind, flag to indicate type of data change (Create | Append)
  • jsonFilters?: IFilter[], alkalmazott JSON-szűrők gyűjteményejsonFilters?: IFilter[], collection of applied json filters
  • isInFocus?: boolean, jelölő annak jelölésére, hogy a vizualizáció fókusz módban van-eisInFocus?: boolean, flag to indicate if the visual is in focus mode or not

enumerateObjectInstances optionalenumerateObjectInstances optional

Ezt a metódust a képességekben felsorolt összes objektum esetén meghívja a rendszer.This method is called for every object listed in the capabilities. A kapcsolók (jelenleg csak a név) használatával egy VisualObjectInstanceEnumeration elemet ad vissza, amely ismerteti a tulajdonság megjelenítési módját.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, az objektum neveobjectName: string, name of the object

destroy optionaldestroy optional

A destroy függvényt akkor hívja meg a rendszer, amikor eltávolítja a memóriából a vizualizációt, és olyan tisztítási feladatokhoz használható, mint például az eseményfigyelők eltávolítása.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

Megjegyzés

A Power BI általában nem hívja meg a destroy függvényt, mert a vizualizációt tartalmazó teljes IFrame eltávolítása gyorsabb.Power BI generally doesn't call destroy since it's faster to remove the entire IFrame that contains the visual.