Compartilhar via

API de visual

  • Artigo

Todos os visuais começam com uma classe que implementa a interface IVisual. Você pode dar qualquer nome à classe, desde que haja uma classe que implemente com exatidão a interface IVisual.

Observação

O nome da classe do visual deve ser o mesmo que visualClassName no arquivo pbiviz.json.

A classe visual deve implementar os seguintes métodos, conforme mostrado no exemplo abaixo:

  • constructor: um construtor padrão que inicializa o estado do visual
  • update: atualiza os dados do visual
  • getFormattingModel, retorna um modelo de formatação que populam o painel de propriedades (opções de formatação), em que você pode modificar propriedades, conforme necessário
  • destroy: um destrutor padrão para a limpeza
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)
    }
}

construtor

O constructor da classe do visual é chamado quando é criada uma instância do visual. Ele pode ser usado para qualquer operação de configuração necessária para o visual.

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

Essas interfaces são atualizadas a cada nova versão da API. Para obter o formato de interface mais atualizado, acesse nosso repositório do GitHub.

A lista a seguir descreve algumas das propriedades da interface VisualConstructorOptions:

  • element: HTMLElement: uma referência ao elemento DOM que conterá o visual

  • host: IVisualHost: uma coleção de propriedades e serviços que podem ser usados para interagir com o host do visual (Power BI)

    IVisualHost contém os seguintes serviços:

    • createSelectionIdBuilder: gera e armazena metadados para itens selecionáveis em seu visual
    • createSelectionManager: cria a ponte de comunicação usada para notificar o host do visual sobre alterações no estado de seleção; confira API de Seleção.
    • hostCapabilities
    • refreshHostData
    • downloadService: retorna informações de resultado expandidas do download.
    • eventService: retorna informações sobre eventos de renderização.
    • hostEnv
    • displayWarningIcon: retorna mensagem de aviso ou erro.
    • licenseManager: retorna informações sobre a licença.
    • createLocalizationManager: gera um gerente para ajudar com a Localização
    • applyJsonFilter: aplica tipos de filtros específicos. Consulte API de filtro
    • applyCustomSort: permite opções de classificação personalizadas.
    • acquireAADTokenService: retorna informações de autenticação do Microsoft Entra ID.
    • webAccessService: retorna o status de permissão para acessar recursos remotos.
    • openModalDialog: retorna uma caixa de diálogo.
    • persistProperties: permite que os usuários criem configurações persistentes e as salvem junto com a definição do visual, para que fiquem disponíveis na próxima recarga
    • eventService: retorna um serviço de evento para dar suporte a eventos de Renderização
    • storageService: retorna um serviço para ajudar a usar o armazenamento local no visual
    • storageV2Service: retorna um serviço para ajudar a usar a versão 2 do armazenamento local no visual
    • tooltipService: retorna um serviço de dica de ferramenta para ajudar a usar dicas de ferramentas no visual
    • telemetry
    • drill
    • launchUrl: ajuda a iniciar o URL na próxima guia
    • authenticationService: retorna um token do Microsoft Entra ID.
    • locale: retorna uma cadeia de caracteres de localidade; confira Localização
    • instanceId: retorna uma cadeia de caracteres para identificar a atual instância do visual
    • colorPalette: retorna a colorPalette necessária para aplicar cores aos seus dados
    • fetchMoreData: dá suporte ao uso de mais dados do que o limite padrão (1.000 linhas). Consulte Buscar mais dados
    • switchFocusModeState: ajuda a alterar o estado do modo de foco

update

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.

public update(options: VisualUpdateOptions): void

VisualUpdateOptions

  • viewport: IViewport: dimensões do visor no qual o visual deve ser renderizado
  • dataViews: DataView[]: o objeto de visualização de dados que contém todos os dados necessários para renderizar seu visual (um visual normalmente usa a propriedade categórica em DataView)
  • type: VisualUpdateType: sinalizadores que indicam o tipo de dado sendo atualizado (Data | Resize | ViewMode | Style | ResizeEnd)
  • viewMode: ViewMode: sinalizadores que indicam o modo de exibição do visual (View | Edit | InFocusEdit)
  • editMode: EditMode: sinalizador que indica 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)
  • operationKind?: VisualDataChangeOperationKind: sinalizador que indica o tipo de alteração de dados (Create | Append)
  • jsonFilters?: IFilter[]: coleção de filtros JSON aplicados
  • isInFocus?: boolean: sinalizador para indicar se o visual está no modo de foco ou não

getFormattingModel (opcional)

Esse método é chamado uma vez sempre que abrimos o painel de propriedades ou o usuário edita qualquer uma das propriedades no painel. Ele retorna FormattingModel com todas as informações sobre o design, hierarquia, propriedades e valores de formatação mais recentes do painel de propriedades.

getFormattingModel(): visuals.FormattingModel;

destroy (opcional)

A função destroy é chamada quando o visual é descarregado e pode ser usada para tarefas de limpeza, como remover ouvintes de evento.

public destroy(): void

Dica

Geralmente, o Power BI não chama destroy, pois é mais rápido remover o IFrame inteiro que contém o visual.

Conteúdo relacionado