O painel de formato nos visuais personalizados do Power BI

Usando a API versão 5.1 e posterior, os desenvolvedores podem criar visuais com o painel Formatar. 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 API usa o método FormattingModel para personalizar partes dos painéis de formato e análise.

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

Além de todos os recursos antigos do painel de formatação, o modelo de formatação dá suporte a funcionalidades, propriedades e hierarquias do painel de formato atual.

Criar um visual que dê suporte ao painel de Formatação mais recente

Etapas gerais para adicionar suporte ao painel Formatar a um visual personalizado:

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

2. Defina todos os objects personalizáveis em seu arquivo capabilities.json. Esses objetos são mapeados para as propriedades do painel de formatação. 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.

3. Crie o visual personalizado FormattingModel fazendo um dos seguintes procedimentos:

   • Usar formattingmodel util. (Recomendado)
   • Sem esse utilitário, utilize apenas APIs.

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

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

Exemplo de implementação do modelo de formatação

• Modelo de formatação usando o utilitário formattingmodel como exemplo. (Recomendado)
• Modelo de formatação usando apenas APIs exemplo.

Mapear as propriedades de formatação

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

1. Defina o apiVersion no 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 de formatação deve ter um descritor que contenha um objectName e propertyName que corresponda ao nome do objeto e ao nome da propriedade em capabilities.json.

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

Por exemplo, se o objeto circle no seu arquivo capabilities.json estiver 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 da propriedade no arquivo de funcionalidades não corresponde ao do modelo de formatação
• O tipo de propriedade no arquivo de funcionalidades 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 painel de formato.

Formatação de componentes de modelo

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

• Modelo de formatação O maior contêiner de 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 formatação de fatias.

  

• Contêiner de formatação
  O contêiner de agrupamento de propriedades de nível secundário. O contêiner de formatação agrupa fatias de formatação em itens de contêiner separados e permite alternar entre eles usando uma lista suspensa.

  

• Fatia de formatação
  Contêiner de propriedades. Há dois tipos de fatias:

  • Fatia simples: contêiner de propriedade individual
  • Fatia composta: vários contêineres de propriedades relacionadas 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 opções de negrito, itálico e 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 a um tipo de objeto no arquivo capabilities.json.

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

Objetos de Formatação de Recursos

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

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

  • ItemDropdown
  • ItemFlagsSelection

• Declare as propriedades a seguir 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 no objeto apropriado. (Esses tipos são os mesmos das versões de API anteriores):

  • AutoDropdown
  • AutoFlagSelection

Propriedades de 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 fatia composta:

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

  • Família de Fontes
  • Tamanho da fonte
  • Negrito [opcional]
  • Itálico [opcional]
  • Sublinhado [opcional]

  

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

  Propriedade	Tipo de recursos	Tipo de formatação
  Família de Fontes	Formatação: { fontFamily}	FontPicker
  Tamanho da fonte	Formatação: {fontSize}	NumUpDown
  Ousado	Bool	ToggleSwitch
  Itálico	Bool	ToggleSwitch
  Sublinhado	Bool	ToggleSwitch

• MarginPadding O preenchimento de margem determina o alinhamento do texto na visualização. Ele consiste nas seguintes propriedades:

  • Esquerda
  • Certo
  • Início
  • Base

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

  Propriedade	Tipo de recursos	Tipo de formatação
  Esquerda	Numérico	NumUpDown
  Certo	Numérico	NumUpDown
  Início	Numérico	NumUpDown
  Base	Numérico	NumUpDown

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 os últimos utilitários do modelo de formatação em GitHub – microsoft/powerbi-visuals-utils-formattingmodel: utilitários auxiliares do modelo de formatação de visuais do Power BI

• Você pode encontrar um exemplo de um visual personalizado SampleBarChart que usa a versão 5.1.0 da API e implementa getFormattingModel usando as utilidades mais recentes do modelo de formatação no GitHub – microsoft/PowerBI-visuals-sampleBarChart: Visual Personalizado do Gráfico de Barras para tutorial.

Conteúdo relacionado

Mais perguntas? Pergunte à Comunidade do Power BI.