API visiva

  • Articolo

Tutti gli oggetti visivi iniziano con una classe che implementa l'interfaccia IVisual . È possibile assegnare alla classe qualsiasi nome, purché esista esattamente una classe che implementa l'interfaccia IVisual .

Nota

Il nome della classe visiva deve essere uguale a visualClassName nel pbiviz.json file .

La classe visual deve implementare i metodi seguenti, come illustrato nell'esempio seguente:

  • constructor - Costruttore standard che inizializza lo stato dell'oggetto visivo
  • update - aggiorna i dati dell'oggetto visivo
  • getFormattingModel, restituisce un modello di formattazione che popola il riquadro delle proprietà (opzioni di formattazione) in cui è possibile modificare le proprietà in base alle esigenze
  • destroy - Distruttore standard per la pulizia
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 getFormattingModel(): FormattingModel {
        // returns modern format pane formatting model that contain all format pane components and properties (called on opening format and analytics pane or on editing format properties)
    }
    
    public destroy(): void {
        //one time cleanup code goes here (called once)
    }
}

costruttore

L'oggetto constructor della classe visiva viene chiamato quando viene creata un'istanza dell'oggetto visivo. Può essere usato per qualsiasi operazione di configurazione necessaria per l'oggetto visivo.

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

Queste interfacce vengono aggiornate con ogni nuova versione dell'API. Per il formato di interfaccia più aggiornato, passare al repository GitHub.

L'elenco seguente descrive alcune delle proprietà dell'interfaccia VisualConstructorOptions :

  • element: HTMLElement - Riferimento all'elemento DOM che contiene l'oggetto visivo

  • host: IVisualHost : raccolta di proprietà e servizi che possono essere usati per interagire con l'host visivo (Power BI)

    IVisualHost contiene i servizi seguenti:

    • createSelectionIdBuilder : genera e archivia i metadati per gli elementi selezionabili nell'oggetto visivo
    • createSelectionManager : crea il bridge di comunicazione usato per notificare all'host dell'oggetto visivo le modifiche apportate allo stato di selezione, vedere API di selezione.
    • hostCapabilities
    • refreshHostData
    • downloadService : restituisce le informazioni sui risultati espanse del download.
    • eventService: restituisce informazioni sugli eventi di rendering.
    • hostEnv
    • displayWarningIcon : restituisce un messaggio di errore o di avviso.
    • licenseManager : restituisce le informazioni sulla licenza.
    • createLocalizationManager - genera un responsabile per facilitare la localizzazione
    • applyJsonFilter - applica tipi di filtro specifici. Vedere API filtro
    • applyCustomSort- consente opzioni di ordinamento personalizzate.
    • acquireAADTokenService: restituisce le informazioni di autenticazione di Microsoft Entra ID.
    • webAccessService : restituisce lo stato di autorizzazione per l'accesso alle risorse remote.
    • openModalDialog : restituisce una finestra di dialogo.
    • persistProperties - consente agli utenti di creare impostazioni persistenti e salvarle insieme alla definizione dell'oggetto visivo, in modo che siano disponibili al successivo ricaricamento
    • eventService: restituisce un servizio eventi per supportare gli eventi di rendering
    • storageService : restituisce un servizio che consente di usare l'archiviazione locale nell'oggetto visivo
    • storageV2Service: restituisce un servizio che consente di usare l'archiviazione locale versione 2 nell'oggetto visivo
    • tooltipService : restituisce un servizio di descrizione comando per l'uso delle descrizioni comando nell'oggetto visivo
    • telemetry
    • drill
    • launchUrl - consente di avviare l'URL nella scheda successiva
    • authenticationService : restituisce un token ID Microsoft Entra.
    • locale - restituisce una stringa delle impostazioni locali, vedere Localizzazione
    • instanceId : restituisce una stringa per identificare l'istanza dell'oggetto visivo corrente
    • colorPalette - restituisce il colorePalette necessario per applicare i colori ai dati
    • fetchMoreData - supporta l'uso di più dati rispetto al limite standard (1.000 righe). Vedere Recuperare altri dati
    • switchFocusModeState - consente di modificare lo stato della modalità messa a fuoco

update

Tutti gli oggetti visivi devono implementare un metodo di aggiornamento pubblico chiamato ogni volta che si verifica una modifica nell'ambiente dati o host.

public update(options: VisualUpdateOptions): void

VisualUpdateOptions

  • viewport: IViewport - dimensioni del riquadro di visualizzazione di cui deve essere eseguito il rendering dell'oggetto visivo all'interno
  • dataViews: DataView[] - L'oggetto visualizzazione dati che contiene tutti i dati necessari per eseguire il rendering dell'oggetto visivo (in genere un oggetto visivo usa la proprietà categorica in DataView)
  • type: VisualUpdateType- Flag che indicano il tipo di dati da aggiornare | | ( | Ridimensionamento | dati Stile Ridimensionamento dati ResizeEnd)
  • viewMode: ViewMode- flag che indicano la modalità di visualizzazione dell'oggetto visivo (Visualizza | Modifica | InFocusEdit)
  • editMode: EditMode- flag che indica la modalità di modifica dell'oggetto visivo (impostazione predefinita avanzata | ) (se l'oggetto visivo supporta AdvancedEditMode, deve eseguire il rendering dei controlli avanzati dell'interfaccia utente solo quando editMode è impostato su Avanzate, vedere AdvancedEditMode)
  • operationKind?: VisualDataChangeOperationKind- flag che indica il tipo di modifica dei dati (Crea | accodamento)
  • jsonFilters?: IFilter[] - raccolta di filtri JSON applicati
  • isInFocus?: boolean - flag per indicare se l'oggetto visivo è in modalità messa a fuoco o meno

getFormattingModel (facoltativo)

Questo metodo viene chiamato una volta ogni volta che si apre il riquadro delle proprietà o l'utente modifica una delle proprietà nel riquadro. Restituisce FormattingModel con tutte le informazioni sulla progettazione, la gerarchia, le proprietà e i valori di formattazione più recenti del riquadro delle proprietà.

getFormattingModel(): visuals.FormattingModel;

destroy (facoltativo)

La funzione destroy viene chiamata quando l'oggetto visivo viene scaricato e può essere usato per le attività di pulizia, ad esempio la rimozione di listener di eventi.

public destroy(): void

Suggerimento

Power BI in genere non chiama destroy perché è più veloce rimuovere l'intero IFrame che contiene l'oggetto visivo.

Contenuto correlato