Vizuálne rozhranie API

Všetky vizuály majú na začiatku triedu, ktorá implementuje rozhranie IVisual. Triedu môžete pomenovať ľubovoľným spôsobom, pokiaľ existuje presne jedna trieda, ktorá implementuje rozhranie IVisual.

Poznámka

Názov vizuálnej triedy sa musí zhodovať visualClassName s názvom v pbiviz.json súbore.

Vizuálna trieda by mala implementovať tieto metódy, ako je uvedené vo vzorke nižšie:

  • constructor, štandardný konštruktér, ktorý inicializuje stav vizuálu
  • update, aktualizuje údaje vizuálu
  • enumerateObjectInstances, vráti objekty, ktoré vypĺňajú tablu vlastností (možnosti formátovania), kde ich môžete podľa potreby upraviť
  • destroy, štandardný deštruktor na čistenie.
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)
    }
}

constructor

Konštruktor triedy vizuálu sa volá pri vytváraní inštancie vizuálu. Možno ho použiť na akékoľvek operácie nastavovania, ktoré vizuál potrebuje.

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

  • element: HTMLElement, odkaz na prvok DOM, ktorý bude obsahovať váš vizuál,

  • host: IVisualHost, kolekcia vlastností a služieb, ktoré možno použiť na interakciu s hostiteľom vizuálu (Power BI).

    IVisualHost obsahuje nasledovné služby:

    • createSelectionIdBuilder – generuje a ukladá metaúdaje pre položky dostupné na výber vo vašom vizuáli,
    • createSelectionManager – vytvára komunikačný most používaný na oboznamovanie hostiteľa vizuálu so zmenami stavu výberu – pozrite si informácie o rozhraní API na výber,
    • createLocalizationManager – vygeneruje manažéra na pomoc s lokalizáciou,
    • allowInteractions: boolean, boolovský príznak, ktorý naznačuje, či by vizuál mal alebo nemal byť interaktívny,
    • applyJsonFilter – používa špecifické typy filtrov, pozrite si informácie o rozhraní API na filtrovanie,
    • persistProperties – umožňuje používateľom uchovať vlastnosti a uložiť ich spolu s definíciou vizuálu, aby boli k dispozícii pri ďalšom načítaní,
    • eventService – vráti službu udalosti na podporu udalostí vykresľovania,
    • storageService – vráti službu, ktorá pomáha s používaním lokálneho ukladacieho priestoru vo vizuáli,
    • authenticationService – generuje službu, ktorá pomáha s overením používateľov,
    • tooltipService – vráti službu pre názvy tlačidiel na pomoc s používaním názvov tlačidiel vo vizuáli,
    • launchUrl – pomáha spustiť URL adresu na ďalšej karte,
    • locale – vráti reťazec miestneho nastavenia, pozrite si informácie o lokalizácii,
    • instanceId – vráti reťazec na identifikáciu aktuálnej inštancie vizuálu,
    • colorPalette – vráti colorPalette, službu požadovanú na použitie farieb pre vaše údaje,
    • fetchMoreData – podporuje používanie väčšieho počtu údajov, než je štadardný limit (1 tis. riadkov),
    • switchFocusModeState – pomáha zmeniť stav režimu zamerania.
  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;
  }

update

Všetky vizuály musia implementovať metódu verejnej aktualizácie, ktorá sa volá vždy, keď dôjde k zmene údajov alebo hostiteľského prostredia.

public update(options: VisualUpdateOptions): void

VisualUpdateOptions

  • viewport: IViewport, dimenzie zobrazenia, v rámci ktorého by mal byť vizuál vykreslený,
  • dataViews: DataView[] – ide o objekt DataView, ktorý obsahuje všetky údaje potrebné na vykreslenie vášho vizuálu (váš vizuál bude zvyčajne pre DataView používať kategorickú vlastnosť),
  • type: VisualUpdateType, príznaky označujúce typy aktualizácií údajov( | Veľkosť veľkosti údajov | ViewMode | Štýl | ResizeEnd)
  • viewMode: ViewMode – vykoná označenie príznakom na indikovanie režimu zobrazenia vizuálu (View | Edit | InFocusEdit),
  • editMode: EditMode – vykoná označenie príznakom na indikovanie režimu úprav (Default | Advanced) (ak vizuál podporuje AdvancedEditMode, mal by vykresliť rozšírené ovládacie prvky používateľského rozhrania len vtedy, keď je položka editMode nastavená na hodnotu Advanced, pozrite si informácie o režime AdvancedEditMode),
  • operationKind?: VisualDataChangeOperationKind – vykoná označenie príznakom, aby sa indikoval typ zmeny údajov (Create | Append),
  • jsonFilters?: IFilter[], kolekcia použitých filtrov json,
  • isInFocus?: boolean – vykoná označenie príznakom, aby sa indikovalo, či sa vizuál nachádza v režime zamerania alebo nie.

enumerateObjectInstances (optional)

Táto metóda sa používa pre všetky object uvedené v capabilities.json súbore. Pre každú object (momentálne len názov) vrátite VisualObjectInstanceEnumeration informácie o tom, ako zobraziť túto vlastnosť.

enumerateObjectInstances(options:EnumerateVisualObjectInstancesOptions):VisualObjectInstanceEnumeration

EnumerateVisualObjectInstancesOptions

  • objectName: string, názov objektu

zničiť (nepovinné)

Funkcia destroy sa volá vtedy, keď vizuál nie je načítaný, a možno ju použiť na úlohy čistenia, napríklad odstránenie prijímačov udalostí.

public destroy(): void

Poznámka

Power BI zvyčajne nevolá funkciu destroy, pretože je rýchlejšie odstrániť celý prvok IFrame, ktorý obsahuje vizuál.

Ďalšie kroky