Partilhar via

Visual API

  • Artigo

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.

Nota

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

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 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 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

Gorjeta

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

Conteúdos relacionados