API de visualVisual API

Todos os visuais começam com uma classe que implementa a interface IVisual.All visuals start with a class that implements the IVisual interface. Você pode dar qualquer nome à classe, desde que haja uma classe que implemente com exatidão a interface IVisual.You can name the class anything as long as there's exactly one class that implements the IVisual interface.

Observação

O nome da classe do visual deve corresponder ao que está definido no arquivo pbiviz.json.The visual class name must match what's defined in the pbiviz.json file.

Confira a classe do visual de exemplo com os seguintes métodos que devem ser implementados:See the sample visual class with the following methods that should be implemented:

  • constructor, um construtor padrão para inicializar o estado do visualconstructor, a standard constructor to initialize the visual's state
  • update, para atualizar os dados do visualupdate, to update the visual's data
  • enumerateObjectInstances, para retornar objetos para preencher o painel de propriedades (opções de formatação), onde você pode modificá-los conforme necessárioenumerateObjectInstances, to return objects to populate the property pane (formatting options) where you can modify them as needed
  • destroy, um destruidor padrão para limpezadestroy, 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)
    }
}

construtorconstructor

O construtor da classe do visual é chamado quando é criada uma instância para o visual.The constructor of the visual class is called when the visual is instantiated. Ele pode ser usado para qualquer operação de configuração necessária para o visual.It can be used for any set up operations needed by the visual.

constructor(options: VisualConstructorOptions)

VisualConstructorOptionsVisualConstructorOptions

  • element: HTMLElement, uma referência ao elemento DOM que conterá o visualelement: HTMLElement, a reference to the DOM element that will contain your visual

  • host: IVisualHost, uma coleção de propriedades e serviços que podem ser usados para interagir com o host do visual (Power BI)host: IVisualHost, a collection of properties and services that can be used to interact with the visual host (Power BI)

    IVisualHost contém os seguintes serviços: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, gera e armazena metadados para itens selecionáveis em seu visualcreateSelectionIdBuilder, generates and stores metadata for selectable items in your visual
    • createSelectionManager, cria a ponte de comunicação usada para notificar o host do visual sobre as alterações no estado de seleção; confira API de seleção.createSelectionManager, creates the communication bridge used to notify the visual's host on changes in the selection state, see Selection API.
    • createLocalizationManager, gera um gerente para ajudar com a LocalizaçãocreateLocalizationManager, generates a manager to help with Localization
    • allowInteractions: boolean, um sinalizador booliano que sugere se o visual deve ser interativo ou nãoallowInteractions: boolean, a boolean flag which hints whether or not the visual should be interactive
    • applyJsonFilter, aplica tipos de filtro específicos; confira API de filtroapplyJsonFilter, applies specific filter types, see Filter API
    • persistProperties, permite que os usuários mantenham propriedades e as salvem junto com a definição do visual, para que fiquem disponíveis na próxima recargapersistProperties, allows users to persist properties and save them along with the visual definition, so they're available on the next reload
    • eventService, retorna um serviço de evento para dar suporte a eventos de RenderizaçãoeventService, returns an event service to support Render events
    • storageService, retorna um serviço para ajudar a usar o armazenamento local no visualstorageService, returns a service to help use local storage in the visual
    • authenticationService, gera um serviço para ajudar com a autenticação do usuárioauthenticationService, generates a service to help with user authentication
    • tooltipService, retorna um serviço de dica de ferramenta para ajudar a usar dicas de ferramentas no visualtooltipService, returns a tooltip service to help use tooltips in the visual
    • launchUrl, ajuda a iniciar a URL na próxima guialaunchUrl, helps to launch URL in next tab
    • locale, retorna uma cadeia de caracteres de localidade; confira Localizaçãolocale, returns a locale string, see Localization
    • instanceId, retorna uma cadeia de caracteres para identificar a atual instância do visualinstanceId, returns a string to identify the current visual instance
    • colorPalette, retorna a colorPalette necessária para aplicar cores aos seus dadoscolorPalette, returns the colorPalette required to apply colors to your data
    • fetchMoreData, dá suporte ao uso de mais dados do que o limite padrão (mil linhas)fetchMoreData, supports using more data than the standard limit (1K rows)
    • switchFocusModeState, ajuda a alterar o estado do modo de focoswitchFocusModeState, helps to change the focus mode state

atualizarupdate

Todos os visuais devem implementar um método de atualização pública, chamado sempre que há uma alteração no ambiente de dados ou de host.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, dimensões do visor em que o visual deve ser renderizadoviewport: IViewport, dimensions of the viewport that the visual should be rendered within
  • dataViews: DataView[], o objeto DataView que contém todos os dados necessários para renderizar seu visual (o visual normalmente usará a propriedade categórica em 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, sinalizadores para indicar os tipos da atualização (Data | Resize | ViewMode | Style | ResizeEnd)type: VisualUpdateType, flags to indicate the type(s) of this update (Data | Resize | ViewMode | Style | ResizeEnd)
  • viewMode: ViewMode, sinalizadores para indicar o modo de exibição do visual (View | Edit | InFocusEdit)viewMode: ViewMode, flags to indicate the view mode of the visual (View | Edit | InFocusEdit)
  • editMode: EditMode, sinalizador para indicar o modo de edição do visual (Default | Advanced) (se o visual der suporte a AdvancedEditMode, ele deverá renderizar seus controles de interface do usuário avançados somente quando editMode for definido como Advanced; confira AdvancedEditMode)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, sinalizador para indicar o tipo de alteração de dados (Create | Append)operationKind?: VisualDataChangeOperationKind, flag to indicate type of data change (Create | Append)
  • jsonFilters?: IFilter[], coleção de filtros JSON aplicadosjsonFilters?: IFilter[], collection of applied json filters
  • isInFocus?: boolean, sinalizador para indicar se o visual está no modo de foco ou nãoisInFocus?: boolean, flag to indicate if the visual is in focus mode or not

enumerateObjectInstances optionalenumerateObjectInstances optional

Esse método é chamado para cada objeto listado nos recursos.This method is called for every object listed in the capabilities. Usando as opções (atualmente, apenas o nome), você retorna uma VisualObjectInstanceEnumeration com informações sobre como exibir essa propriedade.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, nome do objetoobjectName: string, name of the object

destroy optionaldestroy optional

A função destroy é chamada quando o visual é descarregado e pode ser usada para limpar tarefas, como remover ouvintes de evento.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

Observação

Geralmente, o Power BI não chama destroy, pois é mais rápido remover o IFrame inteiro que contém o visual.Power BI generally doesn't call destroy since it's faster to remove the entire IFrame that contains the visual.