Tutorial: Adicionar opções de formatação a um visual do Power BITutorial: Adding formatting options to a Power BI visual

Nesse tutorial, vamos mostrar como adicionar propriedades comuns ao visual.In this tutorial, we go through how to add common properties to the visual.

Neste tutorial, você aprenderá como:In this tutorial, you learn how to:

  • Adicionar propriedades visuais.Add visual properties.
  • Empacotar o visual.Package the visual.
  • Importar o visual personalizado para um relatório do Power BI Desktop.Import the custom visual to a Power BI Desktop report.

Como adicionar opções de formataçãoAdding formatting options

  1. Na Power BI, selecione o Formato de Página.In Power BI, select the Format page.

    Será exibida uma mensagem informando: Opções de formatação não estão disponíveis para este visual.You should see a message that reads - Formatting options are unavailable for this visual.

    Pincel de formatação

  2. No Visual Studio Code, abra o arquivo capabilities.json.In Visual Studio Code, open the capabilities.json file.

  3. Antes da matriz dataViewMappings, adicione objetos (depois da linha 8).Before the dataViewMappings array, add objects (after line 8).

    "objects": {},
    

    Adicionar objetos

  4. Salve o arquivo capabilities.json.Save the capabilities.json file.

  5. No Power BI, revise as opções de formatação novamente.In Power BI, review the formatting options again.

    Observação

    Se as opções de formatação não forem alteradas, selecione Recarregar visual personalizado.If you do not see the formatting options change then select Reload Custom Visual.

    Exibir opções de formatação

  6. Defina a opção Título como Desligado.Set the Title option to Off. Observe que o visual não exibe mais o nome da medida no canto superior esquerdo.Notice that the visual no longer displays the measure name at the top-left corner.

    A opção de bloco está desativada

    Sem bloco de nome

Adicionar opções de formatação personalizadasAdding custom formatting options

Você pode adicionar propriedades personalizadas para ativar a configuração da cor do círculo, além da largura da borda.You can add custom properties to enable configuring the color of the circle, and also the border width.

  1. No PowerShell, interrompa o visual personalizado.In PowerShell, stop the custom visual.

  2. No Visual Studio Code, no arquivo capabilities.json, insira o seguinte fragmento JSON no objeto rotulado objects.In Visual Studio Code, in the capabilities.json file, insert the following JSON fragment into the object labeled objects.

        {
            "circle": {
                "displayName": "Circle",
                "properties": {
                    "circleColor": {
                        "displayName": "Color",
                        "description": "The fill color of the circle.",
                        "type": {
                            "fill": {
                                "solid": {
                                    "color": true
                                }
                            }
                        }
                    },
                    "circleThickness": {
                        "displayName": "Thickness",
                        "description": "The circle thickness.",
                        "type": {
                            "numeric": true
                        }
                    }
                }
            }
        }
    

    O fragmento JSON descreve um grupo denominado circle, que consiste em duas opções denominadas circleColor e circleThickness.The JSON fragment describes a group named circle, which consists of two options named circleColor and circleThickness.

    Código de espessura do círculo

  3. Salve o arquivo capabilities.json.Save the capabilities.json file.

  4. No painel do Explorer, de dentro da pasta src, selecione settings.ts.In the Explorer pane, from inside the src folder, and then select settings.ts. Esse arquivo representa as configurações para o visual inicial.This file represents the settings for the starter visual.

  5. No arquivo settings.ts, substitua as duas classes pelo código a seguir.In the settings.ts file, replace the two classes with the following code.

    export class CircleSettings {
        public circleColor: string = "white";
        public circleThickness: number = 2;
    }
    export class VisualSettings extends DataViewObjectsParser {
        public circle: CircleSettings = new CircleSettings();
    }
    

    Classes de módulo

    Esse módulo define as duas classes.This module defines the two classes. A classe CircleSettings define duas propriedades com nomes que correspondem aos objetos definidos no arquivo capabilities.json (circleColor e circleThickness) e também define valores padrão.The CircleSettings class defines two properties with names that match the objects defined in the capabilities.json file (circleColor and circleThickness) and also sets default values. A classe VisualSettings herda a classe DataViewObjectParser e adiciona uma propriedade chamada circle, que corresponde ao objeto definido no arquivo capabilities.json, e retorna uma instância de CircleSettings.The VisualSettings class inherits the DataViewObjectParser class and adds a property named circle, which matches the object defined in the capabilities.json file, and returns an instance of CircleSettings.

  6. Salve o arquivo settings.ts.Save the settings.ts file.

  7. Abra o arquivo visual.ts.Open the visual.ts file.

  8. No arquivo visual.ts,In the visual.ts file,

    importar VisualSettings, VisualObjectInstanceEnumeration e EnumerateVisualObjectInstancesOptions:import VisualSettings, VisualObjectInstanceEnumeration and EnumerateVisualObjectInstancesOptions:

    import { VisualSettings } from "./settings";
    import VisualObjectInstanceEnumeration = powerbi.VisualObjectInstanceEnumeration;
    import EnumerateVisualObjectInstancesOptions = powerbi.EnumerateVisualObjectInstancesOptions;
    

    e na classe Visual, adicione a seguinte propriedade:and in the Visual class add the following property:

    private visualSettings: VisualSettings;
    

    Esta propriedade armazena uma referência ao objeto VisualSettings, descrevendo as configurações do visual.This property stores a reference to the VisualSettings object, describing the visual settings.

    Adicionar classe visual

  9. Na classe Visual, adicione o seguinte método antes do método update.In the Visual class, add the following method before the update method. Este método é usado para preencher as opções de formatação.This method is used to populate the formatting options.

    public enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
        const settings: VisualSettings = this.visualSettings || <VisualSettings>VisualSettings.getDefault();
        return VisualSettings.enumerateObjectInstances(settings, options);
    }
    

    Este método é usado para preencher as opções de formatação.This method is used to populate the formatting options.

    Objeto Visual settings

  10. No método update, após a declaração da variável radius, adicione o seguinte código.In the update method, after the declaration of the radius variable, add the following code.

    this.visualSettings = VisualSettings.parse<VisualSettings>(dataView);
    
    this.visualSettings.circle.circleThickness = Math.max(0, this.visualSettings.circle.circleThickness);
    this.visualSettings.circle.circleThickness = Math.min(10, this.visualSettings.circle.circleThickness);
    

    Este código recupera as opções de formato.This code retrieves the format options. Ele ajusta qualquer valor passado para a propriedade circleThickness, convertendo-o para 0 se for negativo ou 10 se for um valor maior que 10.It adjusts any value passed into the circleThickness property, converting it to 0 if negative, or 10 if it's a value greater than 10.

    Variável radius

  11. No elemento circle, modifique o valor em fill style para a seguinte expressão.For the circle element, modify the value passed to the fill style to the following expression.

    this.visualSettings.circle.circleColor
    

    Preenche o elemento circle

  12. No elemento circle, modifique o valor em stroke-width style para a seguinte expressão.For the circle element, modify the value passed to the stroke-width style to the following expression.

    this.visualSettings.circle.circleThickness
    

    Espessura do traço do círculo

  13. Salve o arquivo visual.ts.Save the visual.ts file.

  14. No PowerShell, inicie o visual.In PowerShell, start the visual.

    pbiviz start
    
  15. No Power BI, na barra de ferramentas flutuando acima do visual, selecione Ativar/Desativar Recarga Automática.In Power BI, in the toolbar floating above the visual, select Toggle Auto Reload.

  16. Nas opções de formato visual, expanda Círculo.In the visual format options, expand Circle.

    Formato do círculo

    Modifique as opções de cor e espessura.Modify the color and thickness option.

    Modifique a opção de espessura para um valor menor do que zero e um valor maior do que 10.Modify the thickness option to a value less than zero, and a value higher than 10. Em seguida, observe que o visual atualiza o valor para um mínimo ou máximo tolerável.Then notice the visual updates the value to a tolerable minimum or maximum.

Preparar o visual personalizadoPackaging the custom visual

Insira valores de propriedade para o projeto visual personalizado, atualize o arquivo de ícone e, em seguida, prepare o visual personalizado.Enter property values for the custom visual project, update the icon file, and then package the custom visual.

  1. No PowerShell, interrompa o visual personalizado.In PowerShell, stop the custom visual.

  2. Abra o arquivo biviz.json no Visual Studio Code.Open the pbiviz.json file in Visual Studio Code.

  3. No objeto visual, modifique a propriedade displayName para Circle Card.In the visual object, modify the displayName property to Circle Card.

    No painel Visualizações, passar o mouse sobre o ícone revela o nome de exibição.In the Visualizations pane, hovering over the icon reveals the display name.

    Visual Nome de Exibição

  4. Para a propriedade description, insira o texto a seguir.For the description property, enter the following text.

    Exibe um valor de medida formatado dentro de um círculoDisplays a formatted measure value inside a circle

  5. Preencha supportUrl e gitHubUrl para o visual.Fill supportUrl and gitHubUrl for the visual.

    Exemplo:Example:

    {
        "supportUrl": "https://community.powerbi.com",
        "gitHubUrl": "https://github.com/microsoft/PowerBI-visuals-circlecard"
    }
    
  6. Insira seus detalhes no objeto author.Enter your details in the author object.

  7. Salve o arquivo pbiviz.json.Save the pbiviz.json file.

  8. No objeto assets, observe que o documento define um caminho para um ícone.In the assets object, notice that the document defines a path to an icon. O ícone é a imagem que aparece no painel Visualizações.The icon is the image that appears in the Visualizations pane. Ele deve ser um arquivo PNG, 20 pixels por 20 pixels.It must be a PNG file, 20 pixels by 20 pixels.

  9. No Windows Explorer, copie o arquivo icon.png, e cole-o para substituir o arquivo padrão localizado na pasta assets.In Windows Explorer, copy the icon.png file, and then paste it to replace the default file located at assets folder.

  10. No Visual Studio Code, no painel do Explorer, expanda a pasta assets e, em seguida, selecione o arquivo icon.png.In Visual Studio Code, in the Explorer pane, expand the assets folder, and then select the icon.png file.

  11. Verifique o ícone.Review the icon.

    Imagem do painel de visualização

  12. No Visual Studio Code, verifique se todos os arquivos foram salvos.In Visual Studio Code, ensure that all files are saved.

  13. Para preparar o visual personalizado, no PowerShell, digite o seguinte comando.To package the custom visual, in PowerShell, enter the following command.

    pbiviz package
    

    Pasta dist

Agora o pacote é enviado para a pasta dist do projeto.Now the package is output to the dist folder of the project. O pacote contém tudo o que é necessário para importar o visual personalizado para o serviço do Power BI ou para um relatório do Power BI Desktop.The package contains everything required to import the custom visual into either the Power BI service or a Power BI Desktop report. Você preparou o visual personalizado e agora ele está pronto para uso.You have now packaged the custom visual, and it is now ready for use.

Importar o visual personalizadoImporting the custom visual

Agora você pode abrir o relatório do Power BI Desktop e importar o visual personalizado Circle Card.Now you can open the Power BI Desktop report, and import the Circle Card custom visual.

  1. Abra o Power BI Desktop, crie um novo relatório com qualquer conjunto de dados de amostraOpen Power BI Desktop, create a new report with any sample dataset

  2. No painel Visualizações, selecione as reticências e, em seguida, selecione Importar do arquivo.In the Visualizations pane, select the ellipsis, and then select Import from File.

    Adicionar visualização personalizada à área de trabalho

  3. Na janela de importação, selecione Importar.In the import window, select Import.

  4. Na janela aberta, acesse a pasta dist no diretório do projeto.In the Open window, navigate to the dist folder in your project directory.

  5. Selecione o arquivo circleCard.pbiviz e, em seguida, selecione Abrir.Select the circleCard.pbiviz file, and then select Open.

  6. Após a importação bem-sucedida, selecione OK.When the visual has successfully imported, select OK.

  7. Verifique se o visual foi adicionado ao painel Visualizações.Verify that the visual has been added to the Visualizations pane.

    Exibir no painel de visualização do Power BI Desktop

  8. Passe o mouse sobre o ícone Circle Card e observe a dica de ferramenta que aparece.Hover over the Circle Card icon, and notice the tooltip that appears.

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.

Próximas etapasNext steps

É possível listar seu visual desenvolvido recentemente para outras pessoas usarem enviando-o para o AppSource.You can list your newly developed visual for others to use by submitting it to the AppSource. Para saber mais sobre esse processo, veja Publicar visuais do Power BI no AppSource.For more information on this process reference Publish Power BI visuals to AppSource.