Integração do sistema de visuais do Power BIPower BI visuals system integration

O artigo descreve como os visuais se integram ao Power BI e como um usuário pode interagir com um visual no Power BI.The article describes how visuals integrate with Power BI and how a user can interact with a visual in Power BI.

A figura a seguir descreve como são processadas no Power BI as ações comuns baseadas em visuais que um usuário executa, como selecionar um indicador.The following figure depicts how common visual-based actions that a user takes, like selecting a bookmark, are processed in Power BI.

Diagrama de ações de visuais no Power BI

Os visuais obtêm atualizações do Power BIVisuals get updates from Power BI

Um visual chama o método update para receber atualizações do Power BI.A visual calls an update method to get updates from Power BI. O método update geralmente contém a lógica principal do visual e é responsável pela renderização do gráfico ou pela visualização dos dados.The update method usually contains the main logic of the visual and is responsible for rendering a chart or visualizing data.

As atualizações são disparadas quando o visual chama o método update.Updates are triggered when the visual calls the update method.

Padrões de ações e atualizaçõesAction and update patterns

As ações e atualizações subsequentes nos visuais do Power BI ocorrem em um destes três padrões:Actions and subsequent updates in Power BI visuals occur in one of these three patterns:

  • O usuário interage com um visual por meio do Power BI.User interacts with a visual through Power BI.
  • O usuário interage diretamente com o visual.User interacts with the visual directly.
  • O visual interage com o Power BI.Visual interacts with Power BI.

O usuário interage com um visual por meio do Power BIUser interacts with a visual through Power BI

  • O usuário abre o painel de propriedades do visual.A user opens the visual's properties panel.

    Quando um usuário abre o painel de propriedades do visual, o Power BI busca objetos e propriedades com suporte no arquivo capabilities.json do visual.When a user opens the visual's properties panel, Power BI fetches supported objects and properties from the visual's capabilities.json file. Para receber os valores reais de propriedades, o Power BI chama o método enumerateObjectInstances do visual.To receive actual values of properties, Power BI calls the enumerateObjectInstances method of the visual. O visual retorna os valores reais das propriedades.The visual returns actual values of properties.

    Saiba mais em Funcionalidades e propriedades de visuais do Power BI.For more information, see Capabilities and properties of Power BI visuals.

  • O usuário altera uma propriedade do visual no painel de formato.A user changes a property of the visual in the format panel.

    Quando um usuário altera o valor de uma propriedade no painel de formato, o Power BI chama o método update do visual.When a user changes the value of a property in the format panel, Power BI calls the update method of the visual. O Power BI passa o novo objeto options para o método update.Power BI passes in the new options object to the update method. Os objetos contêm os novos valores.The objects contain the new values.

    Para obter mais informações, confira Objetos e propriedades de visuais do Power BI.For more information, see Objects and properties of Power BI visuals.

  • O usuário redimensiona o visual.A user resizes the visual.

    Quando um usuário altera um tamanho de um visual, o Power BI chama o método update com o novo objeto options.When a user changes the size of a visual, Power BI calls the update method with the new options object. Os objetos options têm objetos viewport aninhados que contêm a nova largura e altura do visual.The options objects have nested viewport objects that contain the new width and height of the visual.

  • O usuário aplica o filtro no relatório, página ou nível do visual.A user applies a filter at the report, page, or visual level.

    O Power BI filtra os dados com base nas condições do filtro.Power BI filters data based on filter conditions. O Power BI chama o método update do visual para atualizar o visual com novos dados.Power BI calls the update method of the visual to update the visual with new data.

    O visual obtém uma nova atualização dos objetos options quando há novos dados em um dos objetos aninhados.The visual gets a new update of the options objects when there's new data in one of the nested objects. Como a atualização ocorrerá depende da configuração de mapeamento de exibição de dados do visual.How the update occurs depends on the data view mapping configuration of the visual.

    Para obter mais informações, confira Entender o mapeamento de exibição de dados em visuais do Power BI.For more information, see Understand data view mapping in Power BI visuals.

  • O usuário seleciona um ponto de dados em outro visual do relatório.A user selects a data point in another visual in the report.

    Quando um usuário seleciona um ponto de dados em outro visual do relatório, o Power BI filtra ou realça os pontos de dados selecionados e chama o método update do visual.When a user selects a data point in another visual in the report, Power BI filters or highlights the selected data points and calls the visual's update method. O visual obtém novos dados filtrados ou os mesmos dados com a matriz dos destaques.The visual gets new filtered data, or it gets the same data with an array of highlights.

    Para obter mais informações, confira Realçar pontos de dados em visuais do Power BI.For more information, see Highlight data points in Power BI visuals.

  • O usuário seleciona um indicador no painel de indicadores do relatório.A user selects a bookmark in the bookmarks panel of the report.

    Quando um usuário seleciona um indicador no painel de indicadores do relatório, uma das duas ações pode ocorrer:When a user selects a bookmark in the report's bookmarks panel, one of two actions can occur:

    • O Power BI chama uma função que é passada e registrada pelo método registerOnSelectionCallback.Power BI calls a function that's passed and registered by the registerOnSelectionCallback method. A função de retorno de chamada obtém matrizes de seleções para o indicador correspondente.The callback function gets arrays of selections for the corresponding bookmark.

    • O Power BI chama o método update com um objeto filter correspondente dentro do objeto options.Power BI calls the update method with a corresponding filter object inside the options object.

    Em ambos os casos, o visual deve alterar seu estado de acordo com as seleções recebidas ou com o objeto filter.In either case, the visual must change its state according to the received selections or filter object.

    Para saber mais sobre indicadores e filtros, confira a API de Filtros Visuais em visuais do Power BI.For more information about bookmarks and filters, see Visual Filters API in Power BI visuals.

O usuário interage diretamente com o visualUser interacts with the visual directly

  • Um usuário passa o mouse sobre um elemento de dados.A user hovers the mouse over a data element.

    O visual pode exibir mais informações sobre o ponto de dados por meio da API de Dicas de Ferramentas do Power BI.A visual can display more information about a data point through the Power BI Tooltips API. Quando um usuário passa o mouse sobre um elemento visual, o visual pode manipular o evento e exibir dados sobre o elemento ToolTip associado.When a user hovers the mouse over a visual element, the visual can handle the event and display data about the associated tooltip element. O visual pode exibir a dica de ferramenta padrão ou a dica de ferramenta da página do relatório.The visual can display either a standard tooltip or a report page tooltip.

    Para saber mais, confira Dicas de Ferramentas no Power BI.For more information, see Tooltips in Power BI visuals.

  • Um usuário altera as propriedades do visual.A user changes visual properties. Por exemplo, o usuário expande a árvore e o visual salva o estado nas propriedades.(For example, a user expands a tree and the visual saves state in the visual properties.)

    Um visual pode salvar os valores das propriedades por meio da API do Power BI.A visual can save properties values through the Power BI API. Por exemplo, quando um usuário interage com o visual, que precisa salvar ou atualizar valores de propriedades, o visual pode chamar o método presistProperties.For example, when a user interacts with the visual and the visual needs to save or update properties values, the visual can call the presistProperties method.

  • O usuário seleciona uma URL.A user selects a URL.

    Por padrão, um visual não pode abrir diretamente uma URL.By default, a visual can't open a URL directly. Em vez disso, para abrir uma URL em uma nova guia, o visual pode chamar o método launchUrl e passar a URL como um parâmetro.Instead, to open a URL in a new tab, the visual can call the launchUrl method and pass the URL as a parameter.

    Saiba mais em Criar uma URL de inicialização.For more information, see Create a launch URL.

  • Um usuário aplica um filtro por meio do visual.A user applies a filter through the visual.

    Um visual pode chamar o método applyJsonFilter e passar as condições para filtrar dados em outros visuais.A visual can call the applyJsonFilter method and pass conditions to filter for data in other visuals. Vários tipos de filtros estão disponíveis, incluindo filtros básicos, avançados e de tupla.Several types of filters are available, including Basic, Advanced, and Tuple filters.

    Saiba mais em API de Filtros Visuais em visuais do Power BI.For more information, see Visual Filters API in Power BI visuals.

  • Um usuário seleciona elementos no visual.A user selects elements in the visual.

    Saiba mais sobre seleções em visuais do Power BI em Adicionar interatividade usando as seleções de visual do Power BI.For more information about selections in a Power BI visual, see Add interactivity by using Power BI visual selections.

O visual interage com o Power BIVisual interacts with Power BI

  • O visual solicita mais dados do Power BI.A visual requests more data from Power BI.

    O visual processa os dados por partes.A visual processes data part by part. O método fetchMoreData da API solicita o próximo fragmento do conjunto de dados.The fetchMoreData API method requests the next fragment of data in the dataset.

    Saiba mais em Buscar mais dados do Power BI.For more information, see Fetch more data from Power BI.

  • O serviço de evento dispara.The event service triggers.

    O Power BI pode exportar um relatório para PDF ou enviar um relatório por email (aplica-se somente a visuais certificados).Power BI can export a report to PDF or send a report by e-mail (applies only to certified visuals). Para notificar o Power BI de que a renderização foi concluída e que o visual está pronto para ser capturado como PDF ou para email, o visual deve chamar a API de Renderização de Eventos.To notify Power BI that rendering is finished and that the visual is ready to be captured as PDF or e-mail, the visual should call the Rendering Events API.

    Saiba mais em Exportar relatórios do Power BI para PDF.For more information, see Export reports from Power BI to PDF.

    Para saber mais sobre o serviço de eventos, confira Renderizar eventos em visuais do Power BI.To learn about the event service, see Render events in Power BI visuals.

Próximas etapasNext steps

Você está interessado em criar suas próprias visualizações e adicioná-las ao Microsoft AppSource?Interested in creating visualizations and adding them to Microsoft AppSource? Consulte estes artigos:See these articles: