Tutorial: adicionar opções de formatação ao visual de Cartão circular

Artigo
03/23/2023

Ao criar um visual, você pode adicionar opções para personalizar as propriedades. Alguns dos itens que podem ter formatação personalizada incluem:

Título
Tela de fundo
Borda
Shadow
Cores

Neste tutorial, você aprenderá como:

Adicionar propriedades de formatação ao seu visual.
Empacotar o visual
Importar o visual personalizado para um relatório do Power BI Desktop ou do serviço do Power BI

Pré-requisito

O tutorial explica como adicionar propriedades de formatação comuns a um visual. Vamos usar o visual de cartão circular como exemplo. Vamos adicionar a capacidade de alterar a cor e a espessura do círculo. Se você não tem a pasta do projeto do Cartão circular criada no tutorial, refaça o tutorial antes de continuar.

Como adicionar opções de formatação

No PowerShell, navegue até a pasta do projeto de cartão circular e inicie o visual de cartão circular. Agora o visual é executado enquanto é hospedado no computador.
```
pbiviz start
```
Na Power BI, selecione o Painel de formato.

Você deve ver as opções gerais de formatação, mas não as opções de formatação visual.
No Visual Studio Code, abra o arquivo capabilities.json.
Antes da matriz dataViewMappings, adicione objetos.
```
"objects": {},
```
Salve o arquivo capabilities.json.
No Power BI, revise as opções de formatação novamente.

Observação

Se as opções de formatação não forem alteradas, selecione Recarregar visual personalizado.
Defina a opção Título como Desligado. Observe que o visual não exibe mais o nome da medida no canto superior esquerdo.

Adicionar opções de formatação personalizadas

Vamos adicionar um novo grupo chamado cor para configurar a cor do círculo e a espessura do contorno do círculo.

No PowerShell, digite Ctrl+C para interromper a execução do visual personalizado.

No Visual Studio Code, no arquivo capabilities.json, insira o fragmento JSON a seguir no objeto rotulado como objects.

    "circle": {
        "properties": {
            "circleColor": {
                "type": {
                    "fill": {
                        "solid": {
                            "color": true
                        }
                    }
                }
            },
            "circleThickness": {
                "type": {
                    "numeric": true
                }
            }
        }
    }

Este fragmento JSON descreve um grupo denominado circle, que consiste em duas opções denominadas circleColor e circleThickness.

Salve o arquivo capabilities.json.
No painel do Explorer, vá para a pasta src e selecione settings.ts. Esse arquivo representa as configurações para o visual inicial.

No arquivo settings.ts, substitua as linhas de importação e duas classes pelo código a seguir.

import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

import FormattingSettingsCard = formattingSettings.SimpleCard;
import FormattingSettingsSlice = formattingSettings.Slice;
import FormattingSettingsModel = formattingSettings.Model;

export class CircleSettings extends FormattingSettingsCard{
    public circleColor = new formattingSettings.ColorPicker({
        name: "circleColor",
        displayName: "Color",
        value: { value: "#ffffff" },
        show: true
    });

    public circleThickness = new formattingSettings.NumUpDown({
        name: "circleThickness",
        displayName: "Thickness",
        value: 2,
        show: true
    });

    public name: string = "circle";
    public displayName: string = "Circle";
    public show: boolean = true;
    public slices: FormattingSettingsSlice[] = [this.circleColor, this.circleThickness]
}

export class VisualSettings extends FormattingSettingsModel {
    public circle: CircleSettings = new CircleSettings();
    public cards: FormattingSettingsCard[] = [this.circle];
}

Esse módulo define as duas classes. A classe CircleSettings define duas propriedades com nomes que correspondem aos objetos definidos no arquivo capabilities.json (circleColor e circleThickness) e define os valores padrão. A classe VisualSettings define o objeto circle de acordo com as propriedades descritas no arquivo capabilities.json.

Salve o arquivo settings.ts.
Abra o arquivo visual.ts.

No arquivo visual.ts, importe o :

import { VisualSettings } from "./settings";
import { FormattingSettingsService } from "powerbi-visuals-utils-formattingmodel";

e na classe Visual, adicione as seguintes propriedades:

private visualSettings: VisualSettings;
private formattingSettingsService: FormattingSettingsService;

Esta propriedade armazena uma referência ao objeto VisualSettings, descrevendo as configurações do visual.

Na classe Visual, insira o seguinte como a primeira linha do construtor:
```
this.formattingSettingsService = new FormattingSettingsService();
```
Na classe Visual, adicione o seguinte método após o método update.
```
public getFormattingModel(): powerbi.visuals.FormattingModel {
    return this.formattingSettingsService.buildFormattingModel(this.visualSettings);
}
```
Essa função é chamada em cada renderização de painel de formatação. Ela permite que você selecione quais dos objetos e propriedades você deseja expor aos usuários no painel de propriedades.

No método update, após a declaração da variável radius, adicione o seguinte código.

this.visualSettings = this.formattingSettingsService.populateFormattingSettingsModel(VisualSettings, options.dataViews[0]);
this.visualSettings.circle.circleThickness.value = Math.max(0, this.visualSettings.circle.circleThickness.value);
this.visualSettings.circle.circleThickness.value = Math.min(10, this.visualSettings.circle.circleThickness.value);

Este código recupera as opções de formato. Ela ajusta qualquer valor passado para a propriedade circleThickness e converte-o em um número entre zero e 10.

Screenshot of setting circle thickness to between zero and 10.

No elemento circle, modifique os valores passados para fill style e stroke-width style da seguinte forma:

.style("fill", this.visualSettings.circle.circleColor.value.value)

.style("stroke-width", this.visualSettings.circle.circleThickness.value)

Screenshot of circle elements.

Salve o arquivo visual.ts.
No PowerShell, inicie o visual.
```
pbiviz start
```
No Power BI, na barra de ferramentas flutuando acima do visual, selecione Ativar/Desativar Recarga Automática.
Nas opções de formato visual, expanda Círculo.

Modifique as opções de cor e espessura.

Modifique a opção de espessura para um valor menor do que zero e um valor maior do que 10. Em seguida, observe que o visual atualiza o valor para um mínimo ou máximo tolerável.

Depuração

Para obter dicas de como depurar seu visual personalizado, veja o guia depuração.

Preparar o visual personalizado

Agora que o visual foi concluído e está pronto para ser usado, é hora de empacotá-lo. Um visual empacotado pode ser importado nos relatórios ou no serviço do Power BI para ser usado e aproveitado por outras pessoas.

Quando o visual estiver pronto, siga as instruções em Empacotar um visual do Power BI e, se desejar, compartilhe-o com outras pessoas para que elas possam importá-lo e apreciá-lo.