Visual API

Todos os elementos visuais começam com uma classe que implementa a IVisual interface. Você pode nomear a classe qualquer coisa, desde que haja exatamente uma classe que implemente a IVisual interface.

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

• 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 preenche o painel de propriedades (opções de formatação) onde você pode modificar propriedades conforme necessário
• destroy - um destruidor padrão para 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 visual é chamado quando o visual é instanciado. Ele pode ser usado para qualquer operação de configuração que o visual precisa.

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

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

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

• element: HTMLElement - uma referência ao elemento DOM que contém o seu visual

• host: IVisualHost - uma coleção de propriedades e serviços que podem ser usados para interagir com o host 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, consulte API de seleção.
  • hostCapabilities
  • refreshHostData
  • downloadService - Devolve informação expandida do resultado do download.
  • eventService - retorna informações sobre eventos de renderização.
  • hostEnv
  • displayWarningIcon - retorna mensagem de erro ou aviso.
  • licenseManager - Retorna informações de 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 salvem-nas junto com a definição visual, para que estejam disponíveis na próxima recarga
  • eventService- retorna um serviço deevento 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 o armazenamento local versão 2 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 de ID do Microsoft Entra.
  • locale - retorna uma cadeia de caracteres de localidade, consulte Localização
  • instanceId - retorna uma cadeia de caracteres para identificar a instância visual atual
  • colorPalette - retorna a paleta de cores necessária para aplicar cores aos seus dados
  • fetchMoreData - suporta o uso de mais dados do que o limite padrão (1.000 linhas). Consulte Obter mais dados
  • switchFocusModeState - ajuda a alterar o estado do modo de foco

update

Todos os elementos visuais devem implementar um método de atualização pública que é chamado sempre que há uma alteração nos dados ou no ambiente do host.

public update(options: VisualUpdateOptions): void

VisualUpdateOptions

• viewport: IViewport - dimensões do visor em que o visual deve ser processado
• dataViews: DataView[] - o objeto de exibição de dados que contém todos os dados necessários para renderizar seu visual (um visual geralmente usa a propriedade categórica em DataView)
• type: VisualUpdateType- sinalizadores que indicam o tipo de dados que estão sendo atualizados (Data | Resize | , ViewMode, Style | ResizeEnd)
• viewMode: ViewMode- sinalizadores indicando o modo de visualização do visual (View | Edit | InFocusEdit)
• editMode: EditMode- sinalizador que indica o modo de edição do visual (Default | Advanced) (se o visual suporta AdvancedEditMode, ele deve renderizar seus controles avançados da interface do usuário somente quando editMode estiver definido como Avançado, consulte AdvancedEditMode)
• operationKind?: VisualDataChangeOperationKind- sinalizador indicando o tipo de alteração de dados (Criar | Apêndice)
• 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 cada vez 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 do painel de propriedades, hierarquia, propriedades e valores de formatação mais recentes.

getFormattingModel(): visuals.FormattingModel;

destruir (opcional)

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

public destroy(): void

Conteúdos relacionados

• Estrutura visual do projeto

• API de armazenamento local