Objetos e propriedades de visuais do Power BI
Os objetos descrevem propriedades personalizáveis associadas a um visual. Um objeto pode ter várias propriedades e cada propriedade tem um tipo associado que descreve qual será a propriedade. Este artigo fornece informações sobre objetos e tipos de propriedade.
myCustomObject é o nome interno usado para fazer referência ao objeto dentro dataViewdo .
"objects": {
"myCustomObject": {
"properties": { ... }
}
}
Nome a apresentar e descrição
Nota
O nome para exibição e a descrição foram preteridos da versão 5.1+ da API. O nome para exibição e a descrição agora são adicionados no modelo de formatação em vez do arquivo capabilities.json .
displayName é o nome que será mostrado no painel de propriedades.
description é uma descrição da propriedade de formatação que será mostrada ao usuário como uma dica de ferramenta.
Propriedades
properties é um mapa de propriedades que são definidas pelo desenvolvedor.
"properties": {
"myFirstProperty": {
"type": ValueTypeDescriptor | StructuralTypeDescriptor
}
}
Nota
show é uma propriedade especial que permite que um switch alterne o objeto.
Exemplo:
"properties": {
"show": {
"type": {"bool": true}
}
}
Tipo de propriedade
Existem dois tipos de propriedade: ValueTypeDescriptor e StructuralTypeDescriptor.
Descritor de tipo de valor
ValueTypeDescriptor Os tipos são principalmente primitivos e são normalmente usados como um objeto estático.
Aqui estão alguns dos elementos comuns ValueTypeDescriptor :
export interface ValueTypeDescriptor {
text?: boolean;
numeric?: boolean;
integer?: boolean;
bool?: boolean;
}
Descritor de tipo estrutural
StructuralTypeDescriptor tipos são usados principalmente para objetos ligados a dados.
O tipo mais comum StructuralTypeDescriptor é o preenchimento.
export interface StructuralTypeDescriptor {
fill?: FillTypeDescriptor;
}
Propriedade Gradient
A propriedade gradient é uma propriedade que não pode ser definida como uma propriedade padrão. Em vez disso, você precisa definir uma regra para a substituição da propriedade do seletor de cores (tipo de preenchimento ).
Um exemplo é mostrado no código a seguir:
"properties": {
"showAllDataPoints": {
"type": {
"bool": true
}
},
"fill": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
"fillRule": {
"type": {
"fillRule": {}
},
"rule": {
"inputRole": "Gradient",
"output": {
"property": "fill",
"selector": [
"Category"
]
}
}
}
}
Preste atenção às propriedades fill e fillRule. O primeiro é o seletor de cores, e o segundo é a regra de substituição para o gradiente que substituirá a propriedade fill, visually, quando as condições da regra forem atendidas.
Esse vínculo entre a propriedade fill e a regra de substituição é definido na "rule""output">seção da propriedade fillRule.
"Rule">"InputRole" define qual função de dados aciona a regra (condição). Neste exemplo, se a função "Gradient" de dados contiver dados, a regra será aplicada para a "fill" propriedade.
Um exemplo da função de dados que aciona a regra de preenchimento (the last item) é mostrado no código a seguir:
{
"dataRoles": [
{
"name": "Category",
"kind": "Grouping",
"displayName": "Details",
"displayNameKey": "Role_DisplayName_Details"
},
{
"name": "Series",
"kind": "Grouping",
"displayName": "Legend",
"displayNameKey": "Role_DisplayName_Legend"
},
{
"name": "Gradient",
"kind": "Measure",
"displayName": "Color saturation",
"displayNameKey": "Role_DisplayName_Gradient"
}
]
}
Painel de formatação
Para personalizar as propriedades no painel de formatação, use um dos seguintes métodos, dependendo da versão da API que você está usando.
Nota
O getFormattingModel método API é suportado a partir das versões 5.1+ da API. Para descobrir qual versão você está usando, verifique o apiVersionno arquivo pbiviz.json .
Para usar objetos efetivamente na API versão 5.1+, você precisa implementar o getFormattingModel método.
Este método cria e retorna um modelo de formatação que inclui a hierarquia completa do painel de propriedades de cartões de formatação, grupos de formatação, Também contém propriedades de formatação e seus valores.
Objetos de recursos refletidos no modelo de formatação
Cada propriedade de formatação no modelo de formatação precisa de um objeto correspondente no arquivo capabilities.json . A propriedade formatting deve conter um descritor com um nome de objeto e um nome de propriedade que correspondam exatamente ao objeto de recursos correspondente (os nomes de objeto e propriedade diferenciam maiúsculas de minúsculas).
Por exemplo:
Para obter a seguinte propriedade de formatação no modelo de formatação (Consulte o conteúdo do objeto descritor):
const myCustomCard: powerbi.visuals.FormattingCard = {
displayName: "My Custom Object Card",
uid: "myCustomObjectCard_uid",
groups: [{
displayName: undefined,
uid: "myCustomObjectGroup_uid",
slices: [
{
uid: "myCustomProperty_uid",
displayName: "My Custom Property",
control: {
type: powerbi.visuals.FormattingComponent.ColorPicker,
properties: {
descriptor: {
objectName: "myCustomObject",
propertyName: "myCustomProperty",
selector: null // selector is optional
},
value: { value: "#000000" }
}
}
}
],
}],
};
O objeto correspondente da seção de recursos objects deve ser:
"objects": {
"myCustomObject": {
"properties": {
"myCustomProperty": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
}
}
}
}
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.
Exemplo
O exemplo acima myCustomCard mostra a aparência da propriedade de formatação no modelo de formatação para um objeto com uma propriedade myCustomProperty. Este objeto de propriedade vinculado estaticamente a dataViews[index].metadata.objects.
O seletor no descritor pode ser alterado de acordo com o tipo de seletor escolhido.
Tipos de seletores de objetos
O seletor em enumerateObjectInstances determina onde cada objeto está vinculado no dataView. Existem quatro opções distintas:
estático
Este objeto está vinculado a metadados dataviews[index].metadata.objects, como mostrado aqui.
selector: null
colunas
Este objeto está vinculado a colunas com o arquivo QueryName.
selector: {
metadata: 'QueryName'
}
seletor
Este objeto está vinculado ao elemento para o qual você criou um selectionID . Neste exemplo, vamos supor que criamos selectionIDs para alguns pontos de dados e estamos fazendo looping através deles.
for (let dataPoint in dataPoints) {
...
selector: dataPoint.selectionID.getSelector()
}
Identidade do âmbito
Este objeto está vinculado a valores particulares na interseção de grupos. Por exemplo, se você tiver categorias ["Jan", "Feb", "March", ...] e séries ["Small", "Medium", "Large"], talvez queira ter um objeto na interseção de valores que correspondam FebLargee . Para fazer isso, você pode obter a DataViewScopeIdentity de ambas as colunas, empurrá-las para variável identitiese usar essa sintaxe com o seletor.
selector: {
data: <DataViewScopeIdentity[]>identities
}