Visual APIVisual API

Alle visuals beginnen met een klasse die de interface IVisual implementeert.All visuals start with a class that implements the IVisual interface. U kunt de klasse elke gewenste naam geven, zolang er maar één klasse is die de interface IVisual implementeert.You can name the class anything as long as there's exactly one class that implements the IVisual interface.

Notitie

De naam van de visualklasse moet overeenkomen met de definitie in het bestand pbiviz.json.The visual class name must match what's defined in the pbiviz.json file.

Bekijk de voorbeeldvisualklasse met de volgende methoden die moeten worden geïmplementeerd:See the sample visual class with the following methods that should be implemented:

  • constructor, een standaardconstructor voor het initialiseren van de status van de visualconstructor, a standard constructor to initialize the visual's state
  • update, voor het bijwerken van de gegevens van de visualupdate, to update the visual's data
  • enumerateObjectInstances, voor het retourneren van objecten om het eigenschappenvenster (opmaakopties) te vullen, waar u deze zo nodig kunt wijzigenenumerateObjectInstances, to return objects to populate the property pane (formatting options) where you can modify them as needed
  • destroy, een standaarddestructor voor opschoningdestroy, 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

De constructor van de visualklasse wordt aangeroepen wanneer de visual wordt geïnstantieerd.The constructor of the visual class is called when the visual is instantiated. Deze kan worden gebruikt voor elke set bewerkingen die nodig zijn voor de visual.It can be used for any set up operations needed by the visual.

constructor(options: VisualConstructorOptions)

VisualConstructorOptionsVisualConstructorOptions

  • element: HTMLElement, een verwijzing naar het DOM-element dat uw visual bevatelement: HTMLElement, a reference to the DOM element that will contain your visual

  • host: IVisualHost, een verzameling eigenschappen en services die kunnen worden gebruikt voor interactie met de visual-host (Power BI)host: IVisualHost, a collection of properties and services that can be used to interact with the visual host (Power BI)

    IVisualHost bevat de volgende services: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, voor het genereren en opslaan van metagegevens voor selecteerbare items in uw visualcreateSelectionIdBuilder, generates and stores metadata for selectable items in your visual
    • createSelectionManager, voor de communicatie waarmee de host van de visual op de hoogte wordt gesteld van wijzigingen in de selectiestatus. Zie Selectie-API voor meer informatie.createSelectionManager, creates the communication bridge used to notify the visual's host on changes in the selection state, see Selection API.
    • createLocalizationManager, voor het genereren van een manager als hulpmiddel bij lokalisatiecreateLocalizationManager, generates a manager to help with Localization
    • allowInteractions: boolean, een Booleaanse vlag die aangeeft of de visual interactief moet zijnallowInteractions: boolean, a boolean flag which hints whether or not the visual should be interactive
    • applyJsonFilter, voor het toepassen van specifieke filtertypen. Zie Filter-API voor meer informatieapplyJsonFilter, applies specific filter types, see Filter API
    • persistProperties, dat gebruikers toestaat eigenschappen persistent te maken en samen met de definitie van de visual op te slaan, zodat ze beschikbaar zijn als de visual opnieuw wordt geladenpersistProperties, allows users to persist properties and save them along with the visual definition, so they're available on the next reload
    • eventService, voor het retourneren van een gebeurtenisservice ter ondersteuning van rendering-gebeurtenisseneventService, returns an event service to support Render events
    • storageService, voor het retourneren van een service voor het gebruik van lokale opslag in de visualstorageService, returns a service to help use local storage in the visual
    • authenticationService, voor het genereren van een service voor gebruikersverificatieauthenticationService, generates a service to help with user authentication
    • tooltipService, voor het retourneren van een knopinfo-service voor het gebruik van knopinfo in de visualtooltipService, returns a tooltip service to help use tooltips in the visual
    • launchUrl, voor de start-URL in het volgende tabbladlaunchUrl, helps to launch URL in next tab
    • locale, voor het retourneren van een tekenreeks voor de landinstelling. Zie Lokalisatie voor meer informatielocale, returns a locale string, see Localization
    • instanceId, voor het retourneren van een tekenreeks om het huidige exemplaar van de visual te identificereninstanceId, returns a string to identify the current visual instance
    • colorPalette, voor het retourneren van het kleurenpalet dat nodig is om kleuren toe te passen op uw gegevenscolorPalette, returns the colorPalette required to apply colors to your data
    • fetchMoreData, voor ondersteuning van het gebruik van meer gegevens dan de standaardlimiet (1000 rijen)fetchMoreData, supports using more data than the standard limit (1K rows)
    • switchFocusModeState, voor het wijzigen van de status van de focusmodusswitchFocusModeState, helps to change the focus mode state

updateupdate

Alle visuals moeten een openbare bijwerkmethode implementeren die wordt aangeroepen bij elke wijziging in de gegevens of hostomgeving.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, afmetingen van de viewport waarin de visual moet worden weergegevenviewport: IViewport, dimensions of the viewport that the visual should be rendered within
  • dataViews: DataView[], het dataView-object dat alle gegevens bevat die nodig zijn om uw visual weer te geven (in uw visual wordt meestal de categorische eigenschap onder DataView gebruikt)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, vlaggen om het soort wijziging(en) aan te geven (Data (gegevens) | Resize (formaatwijziging) | ViewMode (weergavemodus) | Style (stijl) | ResizeEnd (einde van formaatwijziging) )type: VisualUpdateType, flags to indicate the type(s) of this update (Data | Resize | ViewMode | Style | ResizeEnd)
  • viewMode: ViewMode, vlaggen om de weergavemodus van de visual (Weergeven | Bewerken | InFocusEdit) aan te gevenviewMode: ViewMode, flags to indicate the view mode of the visual (View | Edit | InFocusEdit)
  • editMode: EditMode, vlag om de bewerkingsmodus van de visual (Default (standaard) | Advanced (geavanceerd) ) aan te geven (als de visual AdvancedEditMode (geavanceerde bewerkingsmodus) ondersteunt, moeten de geavanceerde gebruikersinterface-elementen alleen worden weergegeven wanneer editMode (bewerkingsmodus) is ingesteld op Advanced. Zie AdvancedEditMode voor meer informatie)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, vlag om het soort gegevenswijziging (Create (maken) | Append (toevoegen) ) aan te gevenoperationKind?: VisualDataChangeOperationKind, flag to indicate type of data change (Create | Append)
  • jsonFilters?: IFilter[], verzameling toegepaste JSON-filtersjsonFilters?: IFilter[], collection of applied json filters
  • isInFocus?: boolean, vlag om aan te geven of de visual zich in de focusmodus bevindtisInFocus?: boolean, flag to indicate if the visual is in focus mode or not

enumerateObjectInstances optionalenumerateObjectInstances optional

Deze methode wordt aangeroepen voor elk object dat in de mogelijkheden wordt vermeld.This method is called for every object listed in the capabilities. U kunt met behulp van de opties (momenteel alleen de naam) een VisualObjectInstanceEnumeration retourneren met informatie over het weergeven van deze eigenschap.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, naam van het objectobjectName: string, name of the object

destroy optionaldestroy optional

De functie destroy wordt aangeroepen wanneer uw visual uit het geheugen wordt verwijderd en kan worden gebruikt voor opschoontaken, zoals het verwijderen van gebeurtenislisteners.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

Notitie

In Power BI wordt destroy doorgaans niet aanroepen, omdat het sneller is om het hele IFrame met de visual te verwijderen.Power BI generally doesn't call destroy since it's faster to remove the entire IFrame that contains the visual.