Usar ferramentas de desenvolvedor para criar visuais personalizadosUse developer tools to create custom visuals

Os visuais personalizados permitem atender às necessidades dos usuários e corresponder ao design do aplicativo.Custom visuals allow you to meet your users' needs and match your app's design. Aprenda como criar um visual personalizado para o Power BI usando as ferramentas de desenvolvedor.Learn how to create a custom visual for Power BI using the developer tools.

Observação

Você pode usar este documento para começar a trabalhar.You can use this document to get up and running. Para obter informações mais detalhadas, veja as informações de referência dentro do repositório git de visuais do Power BI.For more in-depth information, see the reference information within the Power BI Visuals git repo.

RequisitosRequirements

Instalar o NodeJS e as ferramentas do Power BIInstall NodeJS and the Power BI tools

Para criar um visual personalizado, você precisará instalar o NodeJS.In order to create a custom visual, you will need to install NodeJS. O NodeJS é necessário para executar as ferramentas de linha de comando.NodeJS is required to run the command line tools.

  1. Baixe e instale o NodeJS.Download and install NodeJS. A versão 4.0 ou posterior é obrigatória, mas é recomendado ter a 5.0 ou posterior.Version 4.0 or later is required but it is recommended to have 5.0 or later.
  2. Instale as ferramentas de linha de comando.Install the command line tools. Execute o seguinte comando em um prompt de comando.Run the following command from a command prompt.

     npm install -g powerbi-visuals-tools
    
  3. Você pode confirmar se as ferramentas estão instaladas executando o seguinte comando sem parâmetros.You can confirm that the tools are installed by running the following command without any parameters.

     pbiviz
    

    Você verá a saída da ajuda.You should see the help output.

    
          +syyso+/
     oms/+osyhdhyso/
     ym/       /+oshddhys+/
     ym/              /+oyhddhyo+/
     ym/                     /osyhdho
     ym/                           sm+
     ym/               yddy        om+
     ym/         shho /mmmm/       om+
      /    oys/ +mmmm /mmmm/       om+
     oso  ommmh +mmmm /mmmm/       om+
    ymmmy smmmh +mmmm /mmmm/       om+
    ymmmy smmmh +mmmm /mmmm/       om+
    ymmmy smmmh +mmmm /mmmm/       om+
    +dmd+ smmmh +mmmm /mmmm/       om+
          /hmdo +mmmm /mmmm/ /so+//ym/
                /dmmh /mmmm/ /osyhhy/
                  //   dmmd
                        ++
    
        PowerBI Custom Visual Tool
    
     Usage: pbiviz [options] [command]
    
     Commands:
    
     new [name]        Create a new visual
     info              Display info about the current visual
     start             Start the current visual
     package           Package the current visual into a pbiviz file
     update [version]  Updates the api definitions and schemas in the current visual. Changes the version if specified
     help [cmd]        display help for [cmd]
    
     Options:
    
     -h, --help      output usage information
     -V, --version   output the version number
     --install-cert  Install localhost certificate
     

<a name"ssl-setup">

Instalação de certificado do servidorServer Certificate setup

Para habilitar uma visualização dinâmica do visual, é necessário um servidor https confiável.To enable a live preview of your visual, a trusted https server is needed. Antes de começar, você precisará instalar um certificado SSL para permitir que os ativos visuais sejam carregados no navegador da Web.Before you can start, you will need to install an SSL certificate which will allow visual assets to load in your web browser.

Observação

Esta é uma instalação única para a estação de trabalho do desenvolvedor.This is a one-time setup for your developer workstation.

Para adicionar um certificado, execute o seguinte comando.To add a certificate, run the following command.

pbiviz --install-cert

Sistema operacional WindowsWindows OS

  1. Selecione Instalar Certificado....Select Install Certificate....

  2. Selecione Usuário Atual e, em seguida, Avançar.Select Current User and then select Next.

  3. Selecione Colocar todos os certificados no repositório a seguir e selecione Procurar....Select Place all certificate in the following store and select Browse....
  4. Selecione Autoridades de Certificação Confiáveis e, em seguida, OK.Select Trusted Root Certification Authorities and then select OK. Selecione Avançar.Select Next.

  5. Selecione Concluir.Select Finish.

  6. Selecione Sim na caixa de diálogo de aviso de segurança.Select Yes on the security warning dialog.

  7. Feche todos os navegadores que estiverem abertos.Close any browsers that you have open.

Observação

Se o certificado não for reconhecido, poderá ser necessário reiniciar o computador.If the certificate is not recognized, you may need to restart your computer.

OSXOSX

  1. Se o bloqueio na parte superior esquerda estiver bloqueado, selecione-o para desbloquear.If the lock in the upper left is locked, select it to unlock. Pesquise localhost e clique duas vezes no certificado.Search for localhost and double click on the certificate.

  2. Selecione Sempre Confiar e feche a janela.Select Always Trust and close the window.

  3. Insira seu nome de usuário e sua senha.Enter your username and password. Selecione Atualizar Configurações.Select Update Settings.

  4. Feche todos os navegadores que estiverem abertos.Close any browsers that you have open.

Observação

Se o certificado não for reconhecido, poderá ser necessário reiniciar o computador.If the certificate is not recognized, you may need to restart your computer.

Habilitar visualização dinâmica do visual do desenvolvedorEnable live preview of developer visual

Para habilitar uma visualização dinâmica de seu visual personalizado, siga estas etapas.To enable a live preview of your custom visual, follow these steps. Assim, o visual poderá ser usado dentro do serviço do Power BI durante a edição de relatórios.This allows the visual to be used within the Power BI service when editing reports.

  1. Procure app.powerbi.com e entre.Browse and sign into app.powerbi.com.
  2. Selecione o ícone de engrenagem e, em seguida, Configurações.Select the gear icon and then select Settings.

  3. Selecione Desenvolvedor e, em seguida, Habilitar visual do desenvolvedor para teste.Select Developer and then select Enable developer visual for testing.

  4. Selecione o Visual do Desenvolvedor no painel Visualização.Select the Developer Visual in the Visualization pane.

    Observação

    Para isso, é necessário ter executado pbiviz start na pasta do visual no computador de desenvolvimento.This requires that you have run pbiviz start from the visual folder on your development machine. Para saber mais sobre como criar seu visual, consulte Criar um novo visual neste artigo.For more information on creating your visual, see Create a new visual in this article.

  5. Selecione o visual na tela do relatório.Select the visual in the report canvas. Você pode associar dados da mesma maneira que faria com outros visuais.You can bind data in the same way you do other visuals.

Agora você pode começar a desenvolver seu visual.You can now begin developing your visual.

Criar um novo visualCreate a new visual

Você pode criar um novo projeto de visual, executando o comando a seguir.You can create a new visual project by running the following command.

pbiviz new My Visual name

Você pode substituir Nome do Meu Visual pelo nome que deseja dar ao visual.You can replace My Visual Name with the name you want to give the visual. Isso poderá ser alterado posteriormente, modificando os campos name e displayName no arquivo pbiviz.json gerado.This can be changed later by modifying the name and displayName fields within the generated pbiviz.json file.

Esse comando criará uma nova pasta no direto no qual o comando foi executado.This command will create a new folder in the direct where the command was run. Será gerado um modelo básico inicial para seu visual.It will generate a basic starter template for your visual. Quando o comando for concluído, você poderá abrir o diretório e usar seu editor favorito para começar a trabalhar no novo visual.Once the command completes, you can open the directory and use your favorite editor to start working on your new visual.

Testando seu visual no Power BITesting your visual in Power BI

Você pode testar seu visual no serviço do Power BI em relatórios e dashboards.You can test your visual within the Power BI service within reports and dashboards.

Executando seu visualRunning your visual

Você pode executar o visual, fazendo o seguinte.You can run your visual by doing the following.

  1. Abra um prompt.Open a prompt.
  2. Altere o diretório para a pasta do visual.Change your directory to be your visual folder. Esta é a pasta que contém o arquivo pbiviz.json.This is the folder that contains the pbiviz.json file.
  3. Execute o seguinte comando.Run the following command.

    pbiviz start
    

Se você estiver no local errado, será exibido um erro semelhante ao seguinte.If you are in the wrong location, you will see an error similar to the following.

    error  LOAD ERROR Error: pbiviz.json not found. You must be in the root of a visual project to run this command.
        at e (C:\Users\[user]\AppData\Roaming\npm\node_modules\powerbi-visuals-tools\lib\VisualPackage.js:67:35)
        at Function.loadVisualPackage (C:\Users\[user]\AppData\Roaming\npm\node_modules\powerbi-visuals-tools\lib\VisualPackage.js:62:16)
        at Object.<anonymous> (C:\Users\[user]\AppData\Roaming\npm\node_modules\powerbi-visuals-tools\bin\pbiviz-start.js:43:15)
        at Module._compile (module.js:556:32)
        at Object.Module._extensions..js (module.js:565:10)
        at Module.load (module.js:473:32)
        at tryModuleLoad (module.js:432:12)
        at Function.Module._load (module.js:424:3)
        at Module.runMain (module.js:590:10)
        at run (bootstrap_node.js:394:7)

Visualizando seu visual no Power BIViewing your visual in Power BI

Para exibir seu visual em um relatório, acesse o relatório e selecione o visual dentro do painel Visualizações.To view your visual in a report, go to that report and select the visual within the Visualizations pane.

Observação

Você deve executar o comando pbiviz start antes de fazer isso, conforme a descrição na seção Executando seu visual.You must run the pbiviz start command before doing this as discribed in the Running your visual section.

Você verá o modelo inicial do visual.You will then see the starter template for the visual.

Item da barra de ferramentasToolbar item DescriçãoDescription
Atualizar o visualRefresh visual Atualize o visual manualmente se o recarregamento automático estiver desabilitado.Manually refresh the visual if auto reload is disabled.
Ativar/desativar recarregamento automáticoToggle auto reload Quando ativado, o visual será atualizado automaticamente sempre que você salvar seu arquivo de visual.When turned on, the visual will automatically update every time you save your visual file.
Mostrar exibição de dadosShow dataview Mostra a exibição de dados subjacente do visual para depuraçãoShows the visual's underlying data view for debugging
Obter ajudaGet help Documentação no GitHubDocumentation within GitHub
Enviar comentáriosSend feedback Queremos saber se existe alguma forma de melhorarmos a experiência!Let us know if there is anyway we can improve the experience! (Requer uma conta do GitHub)(Requires GitHub account)

Empacotar o visual para usar no Power BI Desktop e em distribuiçõesPackage your visual for use in Power BI Desktop and distribution

Antes de carregar seu visual no Power BI Desktop ou compartilhá-lo com a comunidade na Galeria de Visuais do Power BI, você deverá gerar um arquivo pbiviz.Before you can load your visual into Power BI Desktop, or share it with the community in the Power BI Visual gallery, you'll need to generate a pbiviz file.

Você pode empacotar o visual, fazendo o seguinte.You can package your visual by doing the following.

  1. Abra um prompt.Open a prompt.
  2. Altere o diretório para a pasta do visual.Change your directory to be your visual folder. Esta é a pasta que contém o arquivo pbiviz.json.This is the folder that contains the pbiviz.json file.
  3. Execute o seguinte comando.Run the following command.

    pbiviz package
    

Esse comando criará um pbiviz no diretório dist/ do projeto de visual.This command will create a pbiviz in the dist/ directory of your visual project. Se já houver um arquivo pbiviz presente, ele será substituído.If there is already a pbiviz file present, it will be overwritten.

Atualizando a versão da API de visuaisUpdating the visuals API version

Quando você cria um visual usando pbiviz new, uma cópia das definições de tipo e dos esquemas json apropriados da API é enviada para o diretório do seu visual.When you create a visual using pbiviz new, a copy of the appropriate API type definitions and json schemas are copied into your visual's directory. Você pode usar o comando pbiviz update para atualizar esses arquivos, se necessário.You can use the pbiviz update command to update these files if needed. Isso poderá ser útil se lançarmos uma correção para uma versão anterior da API ou se você desejar atualizar para a última versão da API.This can be useful if we release a fix for a past API version or if you want to update to the latest API version.

Atualizando a versão da API existenteUpdating your existing API version

Se lançarmos uma atualização para uma API existente, você poderá obter a versão mais recente fazendo o seguinte.If we release an update to an existing API, you can get the latest version by doing the following.

#Update your version of pbiviz
npm install -g powerbi-visuals-tools

#Run update from the root of your visual project, where pbiviz.json is located
pbiviz update

Esse comando baixará as ferramentas mais recentes do npm, incluindo as definições de tipo e os esquemas atualizados.This will download the latest tools from npm which include the updated type definitions and schemas. O uso de pbiviz update substituirá a propriedade apiVersion no campo pbiviz.json pela versão mais recente.Using pbiviz update will overwrite the apiVersion property in your pbiviz.json fiel with the latest version.

Atualizando para uma versão diferente da APIUpgrading to a different API version

Você pode atualizar para uma versão diferente da API usando as mesmas etapas mencionadas acima.You can update to a different API version by using the same steps as mentioned above. Você pode especificar explicitamente a versão da API que deseja usar.You can explicitly specify the API version you want to use.

#Update your version of pbiviz
npm install -g powerbi-visuals-tools

#Run update from the root of your visual project, where pbiviz.json is located
pbiviz update 1.2.0

Esse comando atualizaria seu visual para API versão 1.2.0.This would update yoru visual to API version 1.2.0. Você pode substituir 1.2.0 por qualquer versão que deseje usar.You can replace 1.2.0 with whatever version your wanting to use.

Aviso

A versão padrão da API usada pelas ferramentas sempre será a versão estável.The default API version used by the tools will always be the stable version of the API. Todas as versões posteriores à versão padrão da API serão instáveis e estarão sujeitas a alteração.Any versions later than the default API version are unstable and subject to change. Elas podem ter comportamentos inesperados e se comportam de forma diferente entre o serviço do Power BI e o Power BI Desktop.They may have unexpected behaviors and behave differently between the Power BI service and Power BI Desktop. Para saber qual é a versão estável atual da API, veja o log de alterações.For the current stable API version, see the change log. Para obter mais informações sobre as versões de pré-lançamento, veja o roteiro.For more information about pre-release versions, see the roadmap.

Dentro do projeto de visualInside the visual project

Seu projeto de visual é a pasta criada ao executar o comando pbiviz new.Your visual project is the folder that gets created when you run the pbiviz new command.

Estrutura do arquivoFile structure

ItemItem DescriçãoDescription
assets/assets/ Usado para armazenar ativos visuais (ícone, capturas de tela, etc).Used to store visual assets (icon, screenshots, etc).
dist/dist/ Quando você executar pbiviz package, o arquivo pbiviz será gerado aqui.When you run pbiviz package, the pbiviz file will be generated here.
src/src/ Código TypeScript do visual.Typescript code for your visual.
style/style/ Estilos Less para seu visual.Less styles for your visual.
.gitignore.gitignore Informa o git para ignorar os arquivos que não devem ser controlados no repositório.Tells git to ignore files that shouldn't be tracked in the repository.
capabilities.jsoncapabilities.json Usado para definir as funcionalidades do seu visual.Used to define the capabilities of your visual.
package.jsonpackage.json Usado pelo npm para gerenciar módulos.Used by npm to manage modules.
pbiviz.jsonpbiviz.json Arquivo de configuração principal.Main configuration file.
tsconfig.jsontsconfig.json Configurações do compilador de TypeScript.Typescript compiler settings. Saiba mais sobre tsconfig.json.Learn more about tsconfig.json.

pbiviz.jsonpbiviz.json

Este é o arquivo de configuração principal do seu visual.This file is the main configuration file for your visual. Ele contém metadados e informações sobre os arquivos necessários para compilar seu visual.It contains metadata, as well as information about your files, needed to build your visual.

{
    "visual": {
        "name": "myVisual", // internal visual name (should not contain spaces)
        "displayName": "My Visual!", // visual name displayed to user (used in gallery)
        "guid": "PBI_CV_xxxxxxx", // a unique id for this visual MUST BE UNIQUE
        "visualClassName": "Visual" // the entry class for your visual
        "version": "1.0.0", // visual version. Should be semantic version (increment if you update the visual)
        "description": "", // description used in gallery
        "supportUrl": "", // url to where users can get support for this visual
        "gitHubUrl": "" // url to the source in github (if applicable)
    },
    "apiVersion": "1.0.0", //API version this visual was created with
    "author": {
        "name": "", // your name
        "email": "" // your e-mail
    },
    "assets": {
        "icon": "assets/icon.png" // relative path to your icon file (20x20 png)
    },
    "style": "style/visual.less", // relative path to your less file
    "capabilities": "capabilities.json" // relative path to your capabilities definition 
}

Fonte do visual (TypeScript)Visual source (TypeScript)

O código do visual deve ser gravado em TypeScript, que é um superconjunto do JavaScript com suporte a recursos mais avançados e acesso antecipado às funcionalidades do ES6/ES7.Visual code should be written in TypeScript, which is a superset of JavaScript that support more advanced features and early access to ES6/ES7 functionality.

Todos os arquivos TypeScript devem ser armazenados no diretório src/ e adicionados à matriz files em tsconfig.json.All TypeScript files should be stored in the src/ directory and added to the files array in tsconfig.json. Isso permite que o compilador TypeScript os carregue em uma determinada ordem.This allows the TypeScript compiler to load them and in what order.

Quando o visual for criado, todos os TypeScripts serão compilados em um único arquivo JavaScript.When your visual is built, all of the TypeScript will be compiled into a single JavaScript file. Isso permite que você faça referência a elementos exportados de outros arquivos sem precisar executar require neles manualmente, desde que ambos os arquivos estejam listados no tsconfig.This allows you to reference exported elements from other files without needing to manually require them as long as both files are listed in the tsconfig.

Você pode criar quantos arquivos e classes precisar para criar seu visual.You can create as many files and classes as you need to create your visual.

Saiba mais sobre TypeScript.Learn more about TypeScript.

Estilo do visual (Less)Visual style (Less)

A definição de estilo do visual é realizada usando CSS (folhas de estilos em cascata).Visual styling is handled using cascading style sheets (CSS). Para facilitar, usamos o pré-compilador de Less que dá suporte a alguns recursos avançados como aninhamento, variáveis, mesclagens, condições, loops, etc. Se não quiser usar esses recursos, escreva apenas o CSS simples no arquivo Less.For your convience, we use the Less pre-compiler which supports some advanced features such as nesting, variables, mixins, conditions, loops, etc. If you don't want to use any of these features, you can just write plain CSS in the Less file.

Todos os arquivos Less devem ser armazenados no diretório style/.All Less files should be stored in the style/ directory. O arquivo especificado no campo style dentro do arquivo pbiviz.json será carregado.The file specified under the style field within your pbiviz.json file will be loaded. Arquivos adicionais devem ser carregados usando @import.Any additional files should be loaded using @import.

Saiba mais sobre Less.Learn more about Less.

DepuraçãoDebugging

Para obter dicas de como depurar seu visual personalizado, veja o guia depuração.For tips about debugging your custom visual, see the debugging guide.

Envie seu visual para AppSourceSubmit your visual to AppSource

Você pode listar seu visual para outras pessoas usarem, mas enviando-o para o AppSource.You can list your visual for others to use but submitting it to AppSource. Para obter mais informações sobre este processo, consulte Publicar visuais personalizados no AppSource.For more information on this process, see publish custom visuals to AppSource.

Solução de problemasTroubleshooting

Comando Pbiviz não encontrado (ou erros semelhantes)Pbiviz command not found (or similar errors)

Se você executar pbiviz no seu terminal ou na linha de comando, será exibida a tela de ajuda.If you run pbiviz in your terminal / command line, you should see the help screen. Caso contrário, ele não estará instalado corretamente.If not, it is not installed correctly. Verifique se no mínimo a versão 4.0 do NodeJS está instalada.Make sure you have at least the 4.0 version of NodeJS installed.

Para obter mais informações, veja Instalar o NodeJS e as ferramentas do Power BI...For more information, see Install NodeJS and the Power BI tools...

Não é possível localizar o elemento visual de depuração na guia VisualizaçõesCannot find the debug visual in the Visualizations tab

O visual de depuração é semelhante a um ícone de aviso dentro da guia Visualizações.The debug visual looks like a prompt icon within the Visualizations tab.

Se ele não estiver visível, verifique se você o habilitou nas configurações do Power BI.If you don't see it, make sure you have enabled it within the Power BI settings.

Observação

No momento, o visual de depuração somente está disponível no serviço do Power BI, mas não no Power BI Desktop nem no aplicativo móvel.The debug visual is currently only available in the Power BI service and not in Power BI Desktop or the mobile app. O visual empacotado ainda funcionará em todos os lugares.The packaged visual will still work everywhere.

Para obter mais informações, veja Habilitar visualização dinâmica do visual do desenvolvedor...For more information, see Enable live preview of developer visual...

Não é possível contatar o servidor de elemento visualCan't contact visual server

Execute o servidor de visual com o comando pbiviz start no terminal ou na linha de comando da raiz do projeto de visual.Run the visual server with the command pbiviz start in your terminal / command line from the root of your visual project. Se o servidor estiver em execução, provavelmente os certificados SSL não foram instalados corretamente.If the server is running, it is likely that your SSL vertificates weren't installed correctly.

Para obter mais informações, veja Executando seu visual ou Instalação de certificado de servidor.For more information, see Running your visual or Server certificate setup.

Próximas etapasNext steps

Visualizações no Power BIVisualizations in Power BI
Visualizações personalizadas no Power BICustom Visualizations in Power BI
Publicar visuais personalizados na Office StorePublish custom visuals to the Office store
TypeScriptTypeScript
CSS LessLess CSS

Mais perguntas?More questions? Experimente perguntar à Comunidade do Power BITry asking the Power BI Community