API per gli oggetti visiviVisual API

• 03/19/2020
• 3 minuti per la lettura
• • K
  • o

Tutti gli oggetti visivi iniziano con una classe che implementa l'interfaccia IVisual.All visuals start with a class that implements the IVisual interface. È possibile assegnare alla classe qualsiasi nome purché la classe che implementa l'interfaccia IVisual sia esattamente una sola.You can name the class anything as long as there's exactly one class that implements the IVisual interface.

Vedere la classe per gli oggetti visivi di esempio con i metodi da implementare seguenti:See the sample visual class with the following methods that should be implemented:

• constructor, costruttore standard per l'inizializzazione dello stato dell'oggetto visivoconstructor, a standard constructor to initialize the visual's state
• update, per l'aggiornamento dei dati dell'oggetto visivoupdate, to update the visual's data
• enumerateObjectInstances, per restituire gli oggetti necessari a popolare il riquadro delle proprietà (opzioni di formattazione) in cui è possibile modificarli in base alle esigenzeenumerateObjectInstances, to return objects to populate the property pane (formatting options) where you can modify them as needed
• destroy, distruttore standard per la puliziadestroy, 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

Il costruttore della classe per gli oggetti visivi viene chiamato quando viene creata un'istanza dell'oggetto visivo.The constructor of the visual class is called when the visual is instantiated. Può essere usato per qualsiasi operazione di configurazione necessaria per l'oggetto visivo.It can be used for any set up operations needed by the visual.

constructor(options: VisualConstructorOptions)

VisualConstructorOptionsVisualConstructorOptions

• element: HTMLElement, riferimento all'elemento DOM che conterrà l'oggetto visivoelement: HTMLElement, a reference to the DOM element that will contain your visual

• host: IVisualHost, raccolta di proprietà e servizi che possono essere usati per interagire con l'host degli oggetti visivi (Power BI)host: IVisualHost, a collection of properties and services that can be used to interact with the visual host (Power BI)

  IVisualHost contiene i servizi seguenti: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, che genera e archivia i metadati per gli elementi selezionabili nell'oggetto visivocreateSelectionIdBuilder, generates and stores metadata for selectable items in your visual
  • createSelectionManager, che crea il bridge di comunicazione usato per notificare all'host dell'oggetto visivo le modifiche apportate allo stato di selezione. Vedere API di selezione.createSelectionManager, creates the communication bridge used to notify the visual's host on changes in the selection state, see Selection API.
  • createLocalizationManager, che genera uno strumento di gestione per facilitare la localizzazionecreateLocalizationManager, generates a manager to help with Localization
  • allowInteractions: boolean, flag booleano che indica se l'oggetto visivo deve essere interattivo o menoallowInteractions: boolean, a boolean flag which hints whether or not the visual should be interactive
  • applyJsonFilter, che applica tipi di filtro specifici. Vedere API di filtroapplyJsonFilter, applies specific filter types, see Filter API
  • persistProperties, che consente agli utenti di rendere persistente le proprietà e salvarle insieme alla definizione dell'oggetto visivo, in modo che siano disponibili al caricamento successivopersistProperties, allows users to persist properties and save them along with the visual definition, so they're available on the next reload
  • eventService, che restituisce un servizio eventi a supporto degli eventi di renderingeventService, returns an event service to support Render events
  • storageService, che restituisce un servizio che consente di usare una risorsa di archiviazione locale nell'oggetto visivostorageService, returns a service to help use local storage in the visual
  • authenticationService, che genera un servizio per semplificare l'autenticazione utenteauthenticationService, generates a service to help with user authentication
  • tooltipService, che restituisce un servizio descrizioni comandi per consentire l'uso di descrizioni comandi nell'oggetto visivotooltipService, returns a tooltip service to help use tooltips in the visual
  • launchUrl, che consente di avviare un URL nella scheda successivalaunchUrl, helps to launch URL in next tab
  • locale, che restituisce una stringa di impostazioni locali. Vedere Localizzazionelocale, returns a locale string, see Localization
  • instanceId, che restituisce una stringa per identificare l'istanza dell'oggetto visivo correnteinstanceId, returns a string to identify the current visual instance
  • colorPalette, che restituisce la tavolozza dei colori necessaria per applicare colori ai daticolorPalette, returns the colorPalette required to apply colors to your data
  • fetchMoreData, che supporta l'uso di una quantità di dati maggiore rispetto al limite standard (1000 righe)fetchMoreData, supports using more data than the standard limit (1K rows)
  • switchFocusModeState, che consente di modificare lo stato della modalità messa a fuocoswitchFocusModeState, helps to change the focus mode state

updateupdate

Tutti gli oggetti visivi devono implementare un metodo di aggiornamento pubblico che venga chiamato ogni volta che viene apportata una modifica all'ambiente dati o host.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, dimensioni del riquadro di visualizzazione in cui deve essere eseguito il rendering dell'oggetto visivoviewport: IViewport, dimensions of the viewport that the visual should be rendered within
• dataViews: DataView[], oggetto dataview che contiene tutti i dati necessari per il rendering dell'oggetto visivo (l'oggetto visivo usa in genere la proprietà della categoria in 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, flag per indicare il tipo o i tipi di questo aggiornamento (Data | Resize | ViewMode | Style | ResizeEnd)type: VisualUpdateType, flags to indicate the type(s) of this update (Data | Resize | ViewMode | Style | ResizeEnd)
• viewMode: ViewMode, flag per indicare la modalità di visualizzazione dell'oggetto visivo (View | Edit | InFocusEdit)viewMode: ViewMode, flags to indicate the view mode of the visual (View | Edit | InFocusEdit)
• editMode: EditMode, flag per indicare la modalità di modifica dell'oggetto visivo (Default | Advanced) (se l'oggetto visivo supporta AdvancedEditMode, deve eseguire il rendering dei controlli dell'interfaccia utente avanzati solo quando editMode è impostato su Advanced. Vedere 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, flag per indicare il tipo di modifica dei dati (Create | Append)operationKind?: VisualDataChangeOperationKind, flag to indicate type of data change (Create | Append)
• jsonFilters?: IFilter[], raccolta di filtri json applicatijsonFilters?: IFilter[], collection of applied json filters
• isInFocus?: boolean, flag per indicare se l'oggetto visivo è in modalità messa a fuoco o menoisInFocus?: boolean, flag to indicate if the visual is in focus mode or not

enumerateObjectInstances optionalenumerateObjectInstances optional

Questo metodo viene chiamato per ogni oggetto elencato nelle funzionalità.This method is called for every object listed in the capabilities. Quando si usano le opzioni (attualmente solo il nome), viene restituito un VisualObjectInstanceEnumeration con informazioni su come visualizzare questa proprietà.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, nome dell'oggettoobjectName: string, name of the object

destroy optionaldestroy optional

La funzione destroy viene chiamata quando l'oggetto visivo viene scaricato e può essere usata per attività di pulizia, ad esempio la rimozione di listener di eventi.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