Rozhraní API vizuáluVisual API

Všechny vizuály začínají třídou, která implementuje rozhraní IVisual.All visuals start with a class that implements the IVisual interface. Tuto třídu můžete pojmenovat jakkoli, pokud existuje právě jedna třída, která implementuje rozhraní IVisual.You can name the class anything as long as there's exactly one class that implements the IVisual interface.

Poznámka

Název třídy vizuálu se musí shodovat s tím, co je definováno v souboru pbiviz.json.The visual class name must match what's defined in the pbiviz.json file.

Prohlédněte si ukázkovou třídu vizuálu s následujícími metodami, které by měly být implementovány:See the sample visual class with the following methods that should be implemented:

  • constructor – standardní konstruktor pro inicializaci stavu vizuáluconstructor, a standard constructor to initialize the visual's state
  • update – pro aktualizaci dat vizuáluupdate, to update the visual's data
  • enumerateObjectInstances – pro vrácení objektů, které naplní podokno vlastností (možnosti formátování), kde je můžete podle potřeby upravitenumerateObjectInstances, to return objects to populate the property pane (formatting options) where you can modify them as needed
  • destroy – standardní destruktor pro vyčištěnídestroy, 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

Konstruktor třídy vizuálu se volá při vytváření instance vizuálu.The constructor of the visual class is called when the visual is instantiated. Dá se použít pro všechny operace nastavení potřebné pro vizuál.It can be used for any set up operations needed by the visual.

constructor(options: VisualConstructorOptions)

VisualConstructorOptionsVisualConstructorOptions

  • element: HTMLElement – odkaz na element modelu DOM, který bude obsahovat vizuálelement: HTMLElement, a reference to the DOM element that will contain your visual

  • host: IVisualHost – kolekce vlastností a služeb, které lze použít k interakci s hostitelem vizuálu (Power BI)host: IVisualHost, a collection of properties and services that can be used to interact with the visual host (Power BI)

    IVisualHost obsahuje následující služby: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 – generuje a ukládá metadata pro položky ve vizuálu, které lze vybratcreateSelectionIdBuilder, generates and stores metadata for selectable items in your visual
    • createSelectionManager – vytváří komunikační most sloužící k informování hostitele vizuálu o změnách stavu výběru, viz Rozhraní API pro výběrcreateSelectionManager, creates the communication bridge used to notify the visual's host on changes in the selection state, see Selection API.
    • createLocalizationManager – generuje správce pro pomoc s lokalizacícreateLocalizationManager, generates a manager to help with Localization
    • allowInteractions: boolean – logický příznak, který určuje, jestli vizuál má nebo nemá být interaktivníallowInteractions: boolean, a boolean flag which hints whether or not the visual should be interactive
    • applyJsonFilter – aplikuje konkrétní typy filtrů, viz Rozhraní API pro filtryapplyJsonFilter, applies specific filter types, see Filter API
    • persistProperties – umožňuje uživatelům uchovat vlastnosti a uložit je spolu s definicí vizuálu, aby byly dostupné při příštím načtenípersistProperties, allows users to persist properties and save them along with the visual definition, so they're available on the next reload
    • eventService – vrací službu události pro podporu událostí vykreslováníeventService, returns an event service to support Render events
    • storageService – vrací službu, která ve vizuálu pomáhá použít místní úložištěstorageService, returns a service to help use local storage in the visual
    • authenticationService – generuje službu, která pomáhá s ověřováním uživatelůauthenticationService, generates a service to help with user authentication
    • tooltipService – vrací službu popisů, která pomáhá s použitím popisů ve vizuálutooltipService, returns a tooltip service to help use tooltips in the visual
    • launchUrl – pomáhá s adresou URL pro spuštění v další kartělaunchUrl, helps to launch URL in next tab
    • locale – vrací řetězec národního prostředí, viz Lokalizacelocale, returns a locale string, see Localization
    • instanceId – vrací řetězec pro identifikaci aktuální instance vizuáluinstanceId, returns a string to identify the current visual instance
    • colorPalette – vrací colorPalette potřebnou k aplikování barev na datacolorPalette, returns the colorPalette required to apply colors to your data
    • fetchMoreData – podporuje používání více dat než je standardní limit (1 000 řádků)fetchMoreData, supports using more data than the standard limit (1K rows)
    • switchFocusModeState – pomáhá změnit stav detailního režimuswitchFocusModeState, helps to change the focus mode state

updateupdate

Všechny vizuály musí implementovat veřejnou aktualizační metodu, která se volá vždy, když dojde ke změně dat nebo prostředí hostitele.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 – rozměry zobrazení, ve kterém se má vizuál vykreslitviewport: IViewport, dimensions of the viewport that the visual should be rendered within
  • dataViews: DataView[] – objekt zobrazení dat obsahující všechna data potřebná k vykreslení vizuálu (váš vizuál bude zpravidla používat kategorickou vlastnost v rámci 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 – příznaky pro určení typů této aktualizace (Data | Resize | ViewMode | Style | ResizeEnd)type: VisualUpdateType, flags to indicate the type(s) of this update (Data | Resize | ViewMode | Style | ResizeEnd)
  • viewMode: ViewMode – příznaky pro určení režimu zobrazení vizuálu (View | Edit | InFocusEdit)viewMode: ViewMode, flags to indicate the view mode of the visual (View | Edit | InFocusEdit)
  • editMode: EditMode – příznak určující režim úprav vizuálu (Default | Advanced) (pokud vizuál podporuje AdvancedEditMode, měl by své pokročilé ovládací prvky uživatelského rozhraní vykreslit jen v případě, že je editMode nastavený na Advanced, viz Pokročilý režim úprav)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 – příznak určující typ změny dat (Create | Append)operationKind?: VisualDataChangeOperationKind, flag to indicate type of data change (Create | Append)
  • jsonFilters?: IFilter[] – kolekce použitých filtrů jsonjsonFilters?: IFilter[], collection of applied json filters
  • isInFocus?: boolean – příznak, který určuje, jestli vizuál je nebo není v detailním režimuisInFocus?: boolean, flag to indicate if the visual is in focus mode or not

enumerateObjectInstances optionalenumerateObjectInstances optional

Tato metoda se volá pro všechny objekty uvedené ve schopnostech.This method is called for every object listed in the capabilities. Pomocí parametrů (aktuálně jen název) vrátíte VisualObjectInstanceEnumeration s informacemi o tom, jak tuto vlastnost zobrazit.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 – název objektuobjectName: string, name of the object

destroy optionaldestroy optional

Funkce destroy se volá, když je vizuál uvolněný, a lze ji použít k vyčištění úloh, například k odebrání naslouchacích procesů událostí.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

Poznámka

Power BI obecně destroy nevolá, protože je rychlejší odebrat celý prvek IFrame, který obsahuje vizuál.Power BI generally doesn't call destroy since it's faster to remove the entire IFrame that contains the visual.