Personalizar o painel de formato em visuais personalizados do Power BI
A partir da versão 5.1 da API, os desenvolvedores podem criar visuais que usam o novo painel de formato do Power Bi. 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.
Dica
O método getFormattingModel substitui o método enumerateObjectInstances em versões anteriores da API.
O getFormattingModel retorna um 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 dá suporte a novas funcionalidades de painel de formato, novas propriedades e novas hierarquias.
Para atualizar para a API versão 5.1+, defina a apiVersion no arquivo pbiviz.json como 5.1 ou posterior e faça um dos seguintes:
- Use o utilitário formattingmodel. (Recomendado)
- Sem esse utilitário, use apenas APIs de acordo com o método a seguir.
Criar um visual que dê suporte ao novo painel de formato
Para criar um visual personalizado que usa o novo painel de formato:
Defina todos os
objectspersonalizáveis 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
DisplayNameedescription, são agora opcionais.Crie o FormattingModel de visual personalizado. Defina as propriedades do modelo de formatação de visual personalizado e compile-o usando código (não JSON).
Implemente a API
getFormattingModelna classe visual personalizada que retorna o modelo de formatação de visual personalizado. (Essa API substitui oenumerateObjectInstancesusado em versões anteriores).
Mapear as propriedades de formatação
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:
Defina a
apiVersionno arquivo pbiviz.json como5.1ou posterior.Para cada nome de objeto e nome da propriedade em capabilities.json, crie uma propriedade de formatação correspondente. A propriedade de formatação deve ter um descritor que contenha um
objectNamee umpropertyNameque corresponda ao nome do objeto e ao nome da propriedade em capabilities.json.
As propriedades objects no arquivo de funcionalidades ainda têm o mesmo formato e não precisam ser alteradas.
Por exemplo, se o objeto circle em seu arquivo capabilities.json for definido desta forma:
"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.
Componentes do modelo de formatação
No novo modelo de formatação, os componentes de propriedade são agrupados em categorias e subcategorias lógicas. Esses grupos facilitam a verificação 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 formatação de propriedades. 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 fatias de formatação.
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 de fontes 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 no arquivo capabilities.json e sua classe de tipo correspondente nas propriedades do modelo de formatação moderna:
| Type | Tipo de valor de funcionalidades | Propriedade de formatação |
|---|---|---|
| Boolean | Bool | ToggleSwitch |
| Número | ||
| Lista de Enumeração | enumeration:[] | |
| Cor | Preencher | ColorPicker |
| Gradiente | FillRule | GradientBar: o valor da propriedade deve ser uma cadeia de caracteres que consiste em: minValue[,midValue],maxValue |
| Texto | Texto |
Objetos de formatação de funcionalidades
| Type | Tipo de valor de funcionalidades | Propriedade de formatação |
|---|---|---|
| Tamanho da fonte | FontSize | NumUpDown |
| Família de fontes | FontFamily | FontPicker |
| Alinhamento de linha | Alinhamento | AlignmentGroup |
| Unidades de exibição de rótulo | LabelDisplayUnits | AutoDropDown |
* 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 a lista de itens de enumeração em capabilities.json no objeto apropriado. (Esses tipos são os mesmos das versões anteriores da API):
- 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
Essa fatia mantém todas as propriedades relacionadas à fonte juntas. Ela consiste das 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 funcionalidades Tipo de formatação Família de Fontes Formatação: { fontFamily} FontPicker Tamanho da fonte Formatação: {fontSize} NumUpDown Negrito Bool ToggleSwitch Itálico Bool ToggleSwitch Underline Bool ToggleSwitch O preenchimento de margem MarginPadding determina o alinhamento do texto no visual. Ele consiste das seguintes propriedades:
- Esquerda
- Direita
- Parte superior
- Menor
Cada uma dessas propriedades deve ter um objeto correspondente no arquivo de funcionalidades:
Propriedade Tipo de funcionalidades Tipo de formatação Esquerda Numérico NumUpDown Direita Numérico NumUpDown Parte superior Numérico NumUpDown Menor Numérico NumUpDown
Exemplo: formatação de um cartão de dados
Neste exemplo, mostramos como criar um modelo de formatação de visual personalizado com um cartão.
A 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 da fonte
- Alinhamento de linha
Primeiro, adicione objetos ao arquivo de funcionalidades:
"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;
}
Este é 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 o 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 para o cartão de formatação revertToDefaultDescriptors.
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 possibilita redefinir todas as propriedades dos cartões de formatação ao mesmo tempo clicando no botão redefinir todas as configurações para padrão na barra superior do painel de formato:
Seletor de propriedade de formatação
O seletor opcional no descritor de propriedades de formatação determina onde cada propriedade está associada no dataView. Há quatro opções distintas. Leia sobre eles em tipos de seletores de objetos.
Localização
Para saber mais sobre o recurso de localização e configurar um ambiente de localização, confira Adicionar o idioma local ao visual do Power BI Use o gerenciador de localização para formatar componentes que você deseja localizar:
displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");
Para localizar utilitários do modelo de formatação, confira localização de utilitários de formataçã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”
É recomendável usar os novos utilitários de modelo de formatação no 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 o
getFormattingModelusando os novos utilitários de modelo de formatação no GitHub – microsoft/PowerBI-visuals-sampleBarChart: Visual Personalizado de Gráfico de Barras para tutorial.
Próximas etapas
Mais perguntas? Perguntar à Comunidade do Power BI
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de