Tutorial: Adicionar opções de formatação ao visual do Circle Card

  • Artigo

Ao criar um visual, você pode adicionar opções para personalizar suas propriedades. Alguns dos itens que podem ser formatados de forma personalizada incluem:

  • Título
  • Fundo
  • Border
  • Sombra
  • Cores

Neste tutorial, irá aprender a:

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

Pré-requisito

Este tutorial explica como adicionar propriedades de formatação comuns a um visual. Usaremos o visual do cartão Circle como exemplo. Vamos adicionar a capacidade de alterar a cor e a espessura do círculo. Se você não tiver a pasta de projeto do cartão Circle que criou nesse tutorial, refaça o tutorial antes de continuar.

Adicionar opções de formatação

  1. No PowerShell, navegue até a pasta do projeto do cartão de círculo e inicie o visual do cartão de círculo. O seu visual está agora a ser executado enquanto está alojado no seu computador.

    pbiviz start

  2. No Power BI, selecione o painel Formatar.

    Você deve ver opções gerais de formatação, mas não quaisquer opções de formatação visual.

    Screenshot of formatting panel with only general formatting options.

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

  4. Antes da matriz dataViewMappings , adicione objetos.

    "objects": {},

    Screenshot of capabilities file with empty objects array.

  5. Guarde o ficheiro capabilities.json.

  6. No Power BI, reveja novamente as opções de formatação.

    Nota

    Se não vir as opções de formatação alteradas, selecione Recarregar Visual Personalizado.

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

  7. Defina a opção Título como Desativado. 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

Agora 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 o visual personalizado.

  2. No Visual Studio Code, no capabilities.json arquivo, insira o seguinte fragmento JSON no objeto rotulado objetos.

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

    Este fragmento JSON descreve um grupo chamado circle, que consiste em duas variáveis - circleColor e circleThickness.

  3. Guarde o ficheiro capabilities.json.

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

  5. settings.ts No arquivo, 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" },
        visible: true
    });

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

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

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

    Este 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 valores padrão. A classe VisualSettings define o objeto circle de acordo com as propriedades descritas no capabilities.json arquivo.

  6. Guarde o ficheiro settings.ts.

  7. Abra o ficheiro visual.ts.

  8. No arquivo, importe o visual.ts arquivo :

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

  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);
}

    Esta função é chamada em cada renderização do painel de formatação. Ele 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 código a seguir.

    this.visualSettings = this.formattingSettingsService.populateFormattingSettingsModel(VisualSettings, options.dataViews);
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. Ele ajusta qualquer valor passado para a propriedade circleThickness e o converte 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 o estilo de preenchimento e o estilo de largura do traçado da seguinte maneira:

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

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

    Screenshot of circle elements.

  13. Guarde o ficheiro visual.ts.

  14. No PowerShell, inicie o visual.

    pbiviz start

  15. No Power BI, na barra de ferramentas flutuante acima do visual, selecione Alternar 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 a opção de cor e espessura .

Modifique a opção de espessura para um valor menor que zero e um valor maior 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 sobre como depurar seu visual personalizado, consulte o guia de depuração.

Empacotando o visual personalizado

Agora que o visual está concluído e pronto para ser usado, é hora de empacotá-lo. Um visual empacotado pode ser importado para relatórios ou serviços 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.

Conteúdos relacionados