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:
Defina todos os personalizáveis
objectsem 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, agora são opcionais.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).
Implemente a
getFormattingModelAPI na classe visual personalizada que retorna o modelo de formatação visual personalizado. (Esta API substitui oenumerateObjectInstancesque 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:
Defina o
apiVersionno seu arquivo pbiviz.json como5.1ou posterior.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
objectNamee que corresponda ao nome do objeto epropertyNameao 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 | ||
| Lista de enumeração | enumeração:[] | |
| Color | Fill | Seletor de cores |
| Gradiente | Regra de Preenchimento | GradientBar: o valor da propriedade deve ser string consistindo em: minValue[,midValue],maxValue |
| Texto | 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
getFormattingModelformataçã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