Visualobjekt API

Alle visualiseringer starter med en klasse som implementerer IVisual-grensesnittet. Du kan kalle klassen hva som helst så lenge det finnes nøyaktig én klasse som implementerer IVisual-grensesnittet.

Obs!

Navnet på den visuelle klassen må samsvare med visualClassName i pbiviz.json filen.

Den visuelle klassen bør implementere følgende metoder, som vist i eksemplet nedenfor:

  • constructorer en standard konstruktør som starter den visuelle tilstanden
  • updateoppdaterer dataene for den visuelle effekten
  • enumerateObjectInstancesReturnerer objekter som fyller ut egenskaps ruten (formaterings alternativer), der du kan endre dem etter behov
  • destroy, en standard destruktor for opprydding
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)
    }
}

konstruktør

Konstruktøren av visualiseringsklassen kalles når visualiseringen instansieres. Den kan brukes til å konfigurere operasjoner som er nødvendige for visualiseringen.

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

  • element: HTMLElement, en referanse til DOM-elementet som skal inneholde visualiseringen

  • host: IVisualHost, en samling av egenskaper og tjenester som kan brukes til å samhandle med visualiseringsverten (Power BI)

    IVisualHost inneholder følgende tjenester:

    • createSelectionIdBuilder, genererer og lagrer metadata for elementer i visualiseringen som kan velges
    • createSelectionManager, oppretter kommunikasjonsbroen som brukes til å varsle visualiseringsverten om endringer i valgtilstanden, se valg-API.
    • createLocalizationManager, genererer en leder for å hjelpe deg med lokalisering
    • allowInteractions: boolean, et boolsk flagg som angir om visualiseringen skal være interaktiv
    • applyJsonFilter, bruker spesifikke filtertyper, se filter-API
    • persistProperties, tillater brukere å fastholde egenskaper og lagre dem sammen med definisjonen av visualiseringen, slik at de er tilgjengelige i neste nye innlasting
    • eventService, returnerer en hendelsestjeneste for å støtte gjengivelseshendelser
    • storageService, returnerer en tjeneste for å hjelpe med bruk av lokal lagring i visualiseringen
    • authenticationService, genererer en tjeneste for å hjelpe med brukergodkjenning
    • tooltipService, returnerer en verktøytipstjeneste for å hjelpe med bruk av verktøytips i visualiseringen
    • launchUrl, hjelper med å starte nettadresse i neste fane
    • locale, returnerer en streng for nasjonale innstillinger, se lokalisering
    • instanceId, returnerer en streng for å identifisere den gjeldende visualiseringsforekomsten
    • colorPalette, returnerer colorPalette som kreves for å bruke farger på dataene dine
    • fetchMoreData, støtter bruk av flere data enn standardgrensen (1000 rader)
    • switchFocusModeState, bidrar til å endre fokusmodustilstanden
  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;
  }

oppdatering

Alle visualiseringer må implementere en offentlig oppdateringsmetode som kalles når det er en endring i data- eller vertsmiljøet.

public update(options: VisualUpdateOptions): void

VisualUpdateOptions

  • viewport: IViewport, dimensjoner for visningsporten som visualiseringen skal gjengis i
  • dataViews: DataView[], datavisningsobjektet som inneholder alle data som er nødvendige for å gjengi visualiseringen (visualiseringen bruker vanligvis kategori-egenskapen under DataView)
  • type: VisualUpdateType, flagg for å angi hvilke typer data som oppdateres (data | endre størrelse på | ViewMode | Style | ResizeEnd)
  • viewMode: ViewMode, flagg som angir visningsmodus for visualiseringen (View | Edit | InFocusEdit)
  • editMode: EditMode, flagg som angir redigeringsmodus for visualiseringen (Default | Advanced) (hvis visualiseringen støtter AdvancedEditMode, skal den gjengi de avanserte brukergrensesnittkontrollene bare når editMode er satt til Advanced. Se AdvancedEditMode)
  • operationKind?: VisualDataChangeOperationKind, flagg som angir dataendringstypen (Create | Append)
  • jsonFilters?: IFilter[], samling av brukte JSON-filtre
  • isInFocus?: boolean, flagg som angir om visualiseringen er i fokusmodus eller ikke

enumerateObjectInstances (valg fritt)

Denne metoden kalles for hver object oppført i capabilities.json filen. For hver object (for øyeblikket bare navnet), returnerer du en VisualObjectInstanceEnumeration med informasjon om hvordan du viser denne egenskapen.

enumerateObjectInstances(options:EnumerateVisualObjectInstancesOptions):VisualObjectInstanceEnumeration

EnumerateVisualObjectInstancesOptions

  • objectName: string, navn på objektet

ødeleggelse (valg fritt)

Ødeleggelsesfunksjonen kalles når visualiseringen er lastet ut og kan brukes til oppryddingsoppgaver som å fjerne hendelseslyttere.

public destroy(): void

Obs!

Power BI kaller vanligvis ikke destroy, siden det er raskere å fjerne hele IFrame-filen som inneholder visualiseringen.

Neste trinn