Compartilhar via

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

  • Artigo

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

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

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

    Screenshot of formatting panel with only general formatting options.

  3. No Visual Studio Code, abra o arquivo capabilities.json.

  4. Antes da matriz dataViewMappings, adicione objetos.

    "objects": {},

    Screenshot of capabilities file with empty objects array.

  5. Salve o arquivo capabilities.json.

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

    Screenshot of general and visual formatting options on the formatting pane.

  7. Defina a opção Título como Desligado. Observe que o visual não exibe mais o nome da medida no canto superior esquerdo.

    Screenshot of visualizations pane with the Title switch turned off.

    Screenshot of circle card visual without the title row.

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.

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

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

  3. Salve o arquivo capabilities.json.

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

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

  6. Salve o arquivo settings.ts.

  7. Abra o arquivo visual.ts.

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

  9. Na classe Visual, insira o seguinte como a primeira linha do construtor:

    this.formattingSettingsService = new FormattingSettingsService();

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

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

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

  13. Salve o arquivo visual.ts.

  14. No PowerShell, inicie o visual.

    pbiviz start

  15. No Power BI, na barra de ferramentas flutuando acima do visual, selecione Ativar/Desativar Recarga Automática.

    Screenshot of Toggle Auto Reload icon.

  16. Nas opções de formato visual, expanda Círculo.

    Screenshot of the final circle card visuals format pane elements.

    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.

Próximas etapas