Objetos e propriedades de visuais do Power BI

  • Artigo

Objetos descrevem propriedades personalizáveis associadas um visual. Um objeto pode ter várias propriedades, sendo que 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 de dataView.

"objects": {
    "myCustomObject": {
        "properties": { ... }
    }
}

Nome de exibição e descrição

Observação

O nome de exibição e a descrição foram preteridos da versão 5.1 ou posterior da API. O nome de 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 das propriedades definidas pelo desenvolvedor.

"properties": {
    "myFirstProperty": {
        "type": ValueTypeDescriptor | StructuralTypeDescriptor
    }
}

Observação

show é uma propriedade especial que habilita uma alternância para alternar o objeto.

Exemplo:

"properties": {
    "show": {
        "type": {"bool": true}
    }
}

Tipos de propriedade

Há dois tipos de propriedade: ValueTypeDescriptor e StructuralTypeDescriptor.

Descritor de tipo de valor

Os tipos ValueTypeDescriptor são principalmente primitivos e costumam ser usados como um objeto estático.

Aqui estão alguns dos elementos ValueTypeDescriptor comuns:

export interface ValueTypeDescriptor {
    text?: boolean;
    numeric?: boolean;
    integer?: boolean;
    bool?: boolean;
}

Descritor de tipo estrutural

Tipos StructuralTypeDescriptor são usados principalmente para objetos associados a dados. O tipo StructuralTypeDescriptor mais comum é fill.

export interface StructuralTypeDescriptor {
    fill?: FillTypeDescriptor;
}

Propriedade de gradiente

A propriedade de gradiente não pode ser definida como uma propriedade padrão. Em vez disso, você precisa definir uma regra para substituição da propriedade do seletor de cor (tipo fill).

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. A primeira é o seletor de cor, a segunda é a regra de substituição para 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 seção "rule">"output" da propriedade fillRule.

A propriedade "Rule">"InputRole" define qual função de dados dispara a regra (condição). Neste exemplo, se a função de dados "Gradient" contiver dados, a regra será aplicada à propriedade "fill".

Um exemplo da função de dados que dispara 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 Formatação

Para personalizar as propriedades no painel de formatação, use um dos métodos a seguir, dependendo da versão da API que você está usando.

Observação

O método da API getFormattingModel tem suporte nas versões 5.1 e posteriores da API. Para descobrir qual versão você está usando, verifique apiVersion no arquivo pbiviz.json.

Para usar objetos efetivamente na API versão 5.1 e superior, você precisa implementar o método getFormattingModel.
Esse método compila 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, além de conter propriedades de formatação e seus valores.

Objetos capabilities 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 de formatação deve conter um descritor com um nome de objeto e de propriedade que correspondam exatamente ao objeto capabilities 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 (confira 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 funcionalidades objects deve ser:

    "objects": {
        "myCustomObject": {
            "properties": {
                "myCustomProperty": {
                    "type": {
                         "fill": {
                            "solid": {
                                "color": true
                            }
                        }
                    }
                }
            }
        }
    }

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.

Exemplo

O exemplo myCustomCard acima mostra como seria a propriedade de formatação no modelo de formatação para um objeto com uma propriedade myCustomProperty. Esse 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 no enumerateObjectInstances determina o lugar em que cada objeto é associado no dataView. Há quatro opções distintas:

static

Este objeto está associado a metadados dataviews[index].metadata.objects, como mostrado aqui.

selector: null

colunas

Esse objeto é vinculado a colunas com o QueryName correspondente.

selector: {
    metadata: 'QueryName'
}

seletor

Esse objeto é associado ao elemento para o qual você criou um selectionID. Neste exemplo, vamos pressupor que criamos selectionIDs para alguns pontos de dados e estamos fazendo um loop neles.

for (let dataPoint in dataPoints) {
    ...
    selector: dataPoint.selectionID.getSelector()
}

Identidade do escopo

Esse objeto é vinculado a valores específicos 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 a Feb e Large. Para fazer isso, você poderia obter DataViewScopeIdentity das duas colunas, enviá-las por push para a variável identities e usar essa sintaxe com o seletor.

selector: {
    data: <DataViewScopeIdentity[]>identities
}

Próximas etapas

Dicas de desempenho