Personalizar o painel de formato nos visuais personalizados do Power BI

A partir da API versão 5.1, os desenvolvedores podem criar elementos visuais que usam o novo painel de formato de energia. Os desenvolvedores podem definir os cartões e suas categorias para qualquer propriedade em seu visual personalizado, facilitando o uso desses visuais pelos criadores de relatórios.

A nova API usa o método FormattingModel para personalizar partes dos painéis de formato e análise.

Gorjeta

O getFormattingModel método substitui o método em versões anteriores da enumerateObjectInstances API.

O getFormattingModel retorna a FormattingModel que define a aparência do painel de formatação e análise do visual.

Além de todos os recursos antigos do painel de formatação, o novo modelo de formatação oferece suporte a novos recursos do painel de formatação, novas propriedades e novas hierarquias.

Para atualizar para a API versão 5.1+, defina o apiVersion no arquivo pbiviz.json como 5.1 ou posterior e siga um destes procedimentos:

• Use formattingmodel util. (Recomendado)
• Sem esse util, use apenas APIs de acordo com o seguinte método.

Criar um visual que suporte o novo painel de formato

Para criar um visual personalizado que usa o novo painel de formato:

1. Defina todos os personalizáveis objects em seu arquivo capabilities.json .
   As seguintes propriedades são necessárias para cada objeto:

   • nome do objeto
   • Nome da propriedade
   • Tipo de propriedade

   Todas as outras propriedades, incluindo DisplayName e description, agora são opcionais.

2. Crie o FormattingModel visual personalizado. Defina as propriedades do seu modelo de formatação visual personalizado e crie-o usando código (não JSON).

3. Implemente a getFormattingModel API na classe visual personalizada que retorna o modelo de formatação visual personalizado. (Esta API substitui o enumerateObjectInstances que foi usado em versões anteriores).

Propriedades de formatação do mapa

Se você tiver um visual personalizado criado com uma API mais antiga e quiser migrar para o novo painel de formato ou se estiver criando um novo visual personalizado:

1. Defina o apiVersion no seu arquivo pbiviz.json como 5.1 ou posterior.

2. Para cada nome de objeto e nome de propriedade em capabilities.json, crie uma propriedade de formatação correspondente. A propriedade formatting deve ter um descritor que contenha um objectName e que corresponda ao nome do objeto e propertyName ao nome da propriedade em capabilities.json.

As objects propriedades no arquivo de recursos ainda têm o mesmo formato e não precisam ser alteradas.

Por exemplo, se o circle objeto em seu arquivo capabilities.json for definido assim:

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

A propriedade de formatação em seu modelo deve ser do tipo ColorPicker e ter esta aparência:

control: {
    type: "ColorPicker",
    properties: {
        descriptor: {
            objectName: "circle",
            propertyName: "circleColor"
        },
        value: {
            value: this.visualSettings.circle.circleColor
        }
    }
}

Você receberá um erro se uma das seguintes condições for verdadeira:

• O nome do objeto ou propriedade no arquivo de recursos não corresponde ao do modelo de formatação
• O tipo de propriedade no arquivo de recursos não corresponde ao tipo no modelo de formatação

Modelo de formatação

O modelo de formatação é onde você descreve e personaliza todas as propriedades do seu painel de formato.

Formatando componentes do modelo

No novo modelo de formatação, os componentes de propriedade são agrupados em categorias e subcategorias lógicas. Esses grupos facilitam a digitalização do modelo. Existem os cinco componentes básicos, do maior ao menor:

• Modelo de formatação
  O maior contêiner do painel, usado para formatar a interface frontal do painel. Ele contém uma lista de cartões de formatação.

• Cartão de formatação
  O contêiner de agrupamento de propriedades de nível superior para propriedades de formatação. Cada cartão consiste em um ou mais grupos de formatação, conforme mostrado aqui.

  

• Grupo de formatação
  O contêiner de agrupamento de propriedades de nível secundário. O grupo de formatação é exibido como um contêiner de agrupamento para formatar fatias.

  

• Formatação de fatia
  Recipiente de propriedade. Existem dois tipos de fatias:

  • Fatia simples: recipiente de propriedade individual
  • Fatia composta: vários contêineres de propriedades relacionados agrupados em uma fatia de formatação

  A imagem a seguir mostra os diferentes tipos de fatias. "Fonte" é uma fatia composta que consiste em família de fontes, tamanho e negrito, itálico e opções de sublinhado. "Cor", "unidades de exibição" e as outras fatias são fatias simples com um componente cada.

  

Propriedades de formatação do painel de visualização

Cada propriedade no modelo de formatação deve corresponder e tipo de objeto no arquivo capabilities.json .

A tabela a seguir mostra os tipos de propriedade de formatação no arquivo capabilities.json e sua classe de tipo correspondente nas propriedades do modelo de formatação moderno:

Tipo	Tipo de valor de capacidades	Propriedade de formatação
Booleano	Bool	ToggleSwitch
Número	numérico inteiro	NumUpDown Controlo de deslize
Lista de enumeração	enumeração:[]	ItemDropdown ItemFlagsSelection AutoDropdown AutoFlagsSeleção * Veja a nota abaixo
Color	Fill	Seletor de cores
Gradiente	Regra de Preenchimento	GradientBar: o valor da propriedade deve ser string consistindo em: minValue[,midValue],maxValue
Texto	Texto	TextInput Área de texto

Recursos de formatação de objetos

Tipo	Tipo de valor de capacidades	Propriedade de formatação
Tamanho do tipo de letra	Tamanho do tipo de Letra	NumUpDown
Família de tipos de letra	FontFamily	FontePicker
Alinhamento de linha	Alinhamento	Grupo de alinhamento
Unidades de exibição de etiquetas	LabelDisplayUnits	AutoDropDown

^* A propriedade de formatação da lista de enumeração é diferente no modelo de formatação e no arquivo de recursos.

• Declare as seguintes propriedades na classe de configurações de formatação, incluindo a lista de itens de enumeração:

  • ItemDropdown
  • ItemFlagsSelection

• Declare as seguintes propriedades na classe de configurações de formatação, sem a lista de itens de enumeração. Declare sua lista de itens de enumeração em capabilities.json sob o objeto apropriado. (Estes tipos são os mesmos que nas versões anteriores da API):

  • AutoDropdown
  • AutoFlagSelection

Propriedades da fatia composta

Uma fatia composta de formatação é uma fatia de formatação que contém várias propriedades relacionadas juntas.

Por enquanto temos dois tipos de fatias compostas:

• FontControl
  Isso mantém todas as propriedades relacionadas à fonte juntas. Consiste nas seguintes propriedades:

  • Família de fontes
  • Tamanho do Tipo de Letra
  • Negrito [opcional]
  • Itálico [opcional]
  • Sublinhar [opcional]

  

  Cada uma dessas propriedades deve ter um objeto correspondente no arquivo de recursos:

  Propriedade	Tipo de capacidades	Tipo de formatação
  Família de fontes	Formatação: { fontFamily}	FontePicker
  Tamanho do Tipo de Letra	Formatação: {fontSize}	NumUpDown
  Negrito	Bool	ToggleSwitch
  Italic	Bool	ToggleSwitch
  Sublinhado	Bool	ToggleSwitch

• MarginPadding O preenchimento de margem determina o alinhamento do texto no visual. Consiste nas seguintes propriedades:

  • Left
  • Right
  • Parte Superior
  • Inferior

  Cada uma dessas propriedades deve ter um objeto correspondente no arquivo de recursos:

  Propriedade	Tipo de capacidades	Tipo de formatação
  Left	Numérico	NumUpDown
  Right	Numérico	NumUpDown
  Parte Superior	Numérico	NumUpDown
  Inferior	Numérico	NumUpDown

Exemplo: Formatar um cartão de dados

Neste exemplo, mostramos como criar um modelo de formatação visual personalizado com um cartão.
O cartão tem dois grupos:

• Grupo de controle de fonte com uma propriedade composta
  • Controle de fonte
• Grupo de design de dados com duas propriedades simples
  • Cor do tipo de letra
  • Alinhamento de linhas

Primeiro, adicione objetos ao arquivo de recursos:

"objects": {
        "dataCard": {
            "properties": {
                "displayUnitsProperty": {
                    "type":
                    {
                        "formatting": {
                            "labelDisplayUnits": true
                        }
                    }
                },
                "fontSize": { 
                    "type": {
                        "formatting": {
                            "fontSize": true
                        }
                    }
                },
                "fontFamily": {
                    "type": {
                        "formatting": {
                            "fontFamily": true
                        }
                    }
                },
                "fontBold": {
                    "type": {
                        "bool": true
                    }
                },
                "fontUnderline": {
                    "type": {
                        "bool": true
                    }
                },
                "fontItalic": {
                    "type": {
                        "bool": true
                    }
                },
                "fontColor": {
                    "type": {
                        "fill": {
                            "solid": {
                                "color": true
                            }
                        }
                    }
                },
                "lineAlignment": {
                    "type": {
                        "formatting": {
                            "alignment": true
                        }
                    }
                }
            }
        }
    }

Em seguida, crie o getFormattingModel

    public getFormattingModel(): powerbi.visuals.FormattingModel {
        // Building data card, We are going to add two formatting groups "Font Control Group" and "Data Design Group"
        let dataCard: powerbi.visuals.FormattingCard = {
            description: "Data Card Description",
            displayName: "Data Card",
            uid: "dataCard_uid",
            groups: []
        }

        // Building formatting group "Font Control Group"
        // Notice that "descriptor" objectName and propertyName should match capabilities object and property names
        let group1_dataFont: powerbi.visuals.FormattingGroup = {
            displayName: "Font Control Group",
            uid: "dataCard_fontControl_group_uid",
            slices: [
                {
                    uid: "dataCard_fontControl_displayUnits_uid",
                    displayName:"display units",
                    control: {
                        type: powerbi.visuals.FormattingComponent.Dropdown,
                        properties: {
                            descriptor: {
                                objectName: "dataCard",
                                propertyName:"displayUnitsProperty"
                            },
                            value: 0
                        }
                    }
                },
                // FontControl slice is composite slice, It means it contain multiple properties inside it
                {
                    uid: "data_font_control_slice_uid",
                    displayName: "Font",
                    control: {
                        type: powerbi.visuals.FormattingComponent.FontControl,
                        properties: {
                            fontFamily: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontFamily"
                                },
                                value: "wf_standard-font, helvetica, arial, sans-serif"
                            },
                            fontSize: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontSize"
                                },
                                value: 16
                            },
                            bold: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontBold"
                                },
                                value: false
                            },
                            italic: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontItalic"
                                },
                                value: false
                            },
                            underline: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontUnderline"
                                },
                                value: false
                            }
                        }
                    }
                }
            ],
        };
        // Building formatting group "Font Control Group"
        // Notice that "descriptor" objectName and propertyName should match capabilities object and property names
        let group2_dataDesign: powerbi.visuals.FormattingGroup = {
            displayName: "Data Design Group",
            uid: "dataCard_dataDesign_group_uid",
            slices: [
                // Adding ColorPicker simple slice for font color
                {
                    displayName: "Font Color",
                    uid: "dataCard_dataDesign_fontColor_slice",
                    control: {
                        type: powerbi.visuals.FormattingComponent.ColorPicker,
                        properties: {
                            descriptor:
                            {
                                objectName: "dataCard",
                                propertyName: "fontColor"
                            },
                            value: { value: "#01B8AA" }
                        }
                    }
                },
                // Adding AlignmentGroup simple slice for line alignment
                {
                    displayName: "Line Alignment",
                    uid: "dataCard_dataDesign_lineAlignment_slice",
                    control: {
                        type: powerbi.visuals.FormattingComponent.AlignmentGroup,
                        properties: {
                            descriptor:
                            {
                                objectName: "dataCard",
                                propertyName: "lineAlignment"
                            },
                            mode: powerbi.visuals.AlignmentGroupMode.Horizonal,
                            value: "right"
                        }
                    }
                },
            ]
        };

        // Add formatting groups to data card
        dataCard.groups.push(group1_dataFont);
        dataCard.groups.push(group2_dataDesign);

        // Build and return formatting model with data card
        const formattingModel: powerbi.visuals.FormattingModel = { cards: [dataCard] };
        return formattingModel;
    }

Aqui está o painel resultante:

Redefinir as configurações para o padrão

O novo painel de formato tem a opção de redefinir todos os valores de propriedades do cartão de formatação para padrão clicando no botão Redefinir para padrão que aparece no cartão aberto.

Para habilitar esse recurso, adicione uma lista de descritores de propriedades do cartão de formatação ao cartão revertToDefaultDescriptorsde formatação. O exemplo a seguir mostra como adicionar o botão redefinir para padrão :

let dataCard: powerbi.visuals.FormattingCard = {
    displayName: "Data Card",
    // ... card parameters and groups list

    revertToDefaultDescriptors: [
        {
            objectName: "dataCard",
            propertyName:"displayUnitsProperty"
        },
        {
            objectName: "dataCard",
            propertyName: "fontFamily"
        },

        // ... the rest of properties descriptors 
    ]
};

Adicionar revertToDefaultDescriptors a cartões de formatação também torna possível redefinir todas as propriedades de cartões de formatação de uma só vez, clicando no botão redefinir todas as configurações para padrão na barra superior do painel de formato:

Seletor de propriedades de formatação

O seletor opcional no descritor de propriedades de formatação determina onde cada propriedade está vinculada no dataView. Existem quatro opções distintas. Leia sobre eles em tipos de seletores de objetos.

Localização

Para obter mais informações sobre o recurso de localização e configurar um ambiente de localização, consulte Adicionar o idioma local ao visual do Power BI Use o gerenciador de localização para formatar os componentes que você deseja localizar:

displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");

Para localizar o modelo de formatação utils formatação utils localização.

Recursos do GitHub

• Todas as interfaces de modelo de formatação podem ser encontradas no GitHub - microsoft/powerbi-visuals-api: API de visuais personalizados do Power BI em "formatting-model-api.d.ts"

• Recomendamos usar o novo modelo de formatação utils no GitHub - microsoft/powerbi-visuals-utils-formattingmodel: Power BI visuals formatting model helper utils

• Você pode encontrar um exemplo de um SampleBarChart visual personalizado que usa a API versão 5.1.0 e implementa usando o novo modelo de getFormattingModel formatação utils no GitHub - microsoft/PowerBI-visuals-sampleBarChart: Bar Chart Custom Visual para tutorial.

Conteúdos relacionados

Tem dúvidas? Pergunte à Comunidade do Power BI