Visual API

  • Článek

Všechny vizuály začínají třídou, která implementuje IVisual rozhraní. Třídu můžete pojmenovat tak dlouho, dokud je právě jedna třída, která implementuje IVisual rozhraní.

Poznámka:

Název třídy vizuálu musí být stejný jako visualClassName v pbiviz.json souboru.

Třída vizuálu by měla implementovat následující metody, jak je znázorněno v následující ukázce:

  • constructor – standardní konstruktor, který inicializuje stav vizuálu.
  • update – aktualizuje data vizuálu.
  • getFormattingModel, vrátí formátovací model, který naplní podokno vlastností (možnosti formátování), kde můžete podle potřeby upravit vlastnosti.
  • destroy – standardní destruktor pro vyčištění
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)
    }
}

– konstruktor

Třída constructor vizuálu se volá při vytvoření instance vizuálu. Dá se použít pro všechny operace nastavení, které vizuál potřebuje.

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

Tato rozhraní se aktualizují o každou novou verzi rozhraní API. Pokud chcete aktualizovat formát rozhraní, přejděte do našeho úložiště GitHub.

Následující seznam popisuje některé vlastnosti VisualConstructorOptions rozhraní:

  • element: HTMLElement – odkaz na prvek DOM, který obsahuje vizuál

  • host: IVisualHost – kolekce vlastností a služeb, které lze použít k interakci s hostitelem vizuálu (Power BI)

    IVisualHost obsahuje následující služby:

    • createSelectionIdBuilder - vygeneruje a ukládá metadata pro vybrané položky ve vizuálu.
    • createSelectionManager – vytvoří komunikační most použitý k upozornění hostitele vizuálu o změnách ve stavu výběru, viz rozhraní API pro výběr.
    • hostCapabilities
    • refreshHostData
    • downloadService - vrátí rozšířené informace o výsledku stahování.
    • eventService – vrátí informace o vykreslování událostí.
    • hostEnv
    • displayWarningIcon – vrátí chybovou nebo výstražnou zprávu.
    • licenseManager - vrátí informace o licenci.
    • createLocalizationManager- vygeneruje manažera, který pomůže s lokalizací.
    • applyJsonFilter - použije konkrétní typy filtrů. Viz rozhraní API filtru
    • applyCustomSort – umožňuje vlastní možnosti řazení.
    • acquireAADTokenService– vrátí ověřovací informace o Microsoft Entra ID.
    • webAccessService – vrátí stav oprávnění pro přístup ke vzdáleným prostředkům.
    • openModalDialog - vrátí dialogové okno.
    • persistProperties – umožňuje uživatelům vytvářet trvalá nastavení a ukládat je spolu s definicí vizuálu, takže jsou k dispozici při příštím opětovném načtení.
    • eventService – vrátí službu událostí pro podporu událostí vykreslování .
    • storageService – vrátí službu, která pomáhá používat místní úložiště ve vizuálu.
    • storageV2Service – vrátí službu, která pomáhá používat místní úložiště verze 2 ve vizuálu.
    • tooltipService – vrátí službu popisu, která pomáhá používat popisy ve vizuálu.
    • telemetry
    • drill
    • launchUrl - pomáhá spustit adresu URL na další kartě
    • authenticationService – vrátí token ID Microsoft Entra.
    • locale – vrátí řetězec národního prostředí, viz lokalizace.
    • instanceId – vrátí řetězec pro identifikaci aktuální instance vizuálu.
    • colorPalette – vrátí colorPalette potřebnou k použití barev na vaše data.
    • fetchMoreData – podporuje použití více dat než standardní limit (1 000 řádků). Zobrazit další data
    • switchFocusModeState - pomáhá změnit stav detailního režimu

update

Všechny vizuály musí implementovat metodu veřejné aktualizace, která se volá vždy, když dojde ke změně dat nebo hostitelského prostředí.

public update(options: VisualUpdateOptions): void

VisualUpdateOptions

  • viewport: IViewport – rozměry oblasti zobrazení, kterou má vizuál vykreslit v rámci
  • dataViews: DataView[] – objekt zobrazení dat, který obsahuje všechna data potřebná k vykreslení vizuálu (vizuál obecně používá kategorickou vlastnost v části DataView)
  • type: VisualUpdateType– příznaky označující typ aktualizovaných dat (Změna velikosti dat | ViewMode | Style | ResizeEnd) |
  • viewMode: ViewMode- příznaky označující režim zobrazení vizuálu (Zobrazit | úpravy | InFocusEdit)
  • editMode: EditMode- příznak označující režim úprav vizuálu (výchozí | upřesnit) (pokud vizuál podporuje AdvancedEditMode, měl by vykreslit pokročilé ovládací prvky uživatelského rozhraní pouze v případě, že je vlastnost EditMode nastavena na Upřesnit, viz AdvancedEditMode).
  • operationKind?: VisualDataChangeOperationKind - příznak označující typ změny dat (vytvořit | připojení)
  • jsonFilters?: IFilter[] – kolekce použitých filtrů JSON
  • isInFocus?: boolean - příznak označující, jestli je vizuál v detailním režimu nebo ne

getFormattingModel (volitelné)

Tato metoda se volá jednou při každém otevření podokna vlastností nebo uživatel upraví některou z vlastností v podokně. Vrátí všechny FormattingModel informace o návrhu podokna vlastností, hierarchii, vlastnostech a nejnovějších hodnotách formátování.

getFormattingModel(): visuals.FormattingModel;

destroy (volitelné)

Funkce destroy se volá, když se vizuál uvolní a dá se použít pro úlohy čištění, jako je například odebrání naslouchacích procesů událostí.

public destroy(): void

Tip

Power BI obecně nevolá destroy , protože je rychlejší odebrat celý prvek IFrame, který obsahuje vizuál.

Související obsah