Oggetti e proprietà degli oggetti visivi di Power BI

  • Articolo

Gli oggetti descrivono proprietà personalizzabili associate a un oggetto visivo. Un oggetto può avere più proprietà e ogni proprietà ha un tipo associato che descrive quale sarà la proprietà. Questo articolo fornisce informazioni sugli oggetti e sui tipi di proprietà.

myCustomObject è il nome interno utilizzato per fare riferimento all'oggetto all'interno dataViewdi .

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

Nome visualizzato e descrizione

Nota

Il nome visualizzato e la descrizione sono deprecati dalla versione 5.1+dell'API. Il nome visualizzato e la descrizione vengono ora aggiunti nel modello di formattazione anziché nel file capabilities.json .

displayName è il nome che verrà visualizzato nel riquadro delle proprietà. description è una descrizione della proprietà di formattazione che verrà visualizzata all'utente come descrizione comando.

Proprietà

properties è una mappa di proprietà definite dallo sviluppatore.

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

Nota

show è una proprietà speciale che consente a un commutatore di attivare o disattivare l'oggetto.

Esempio:

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

Tipi di proprietà

Esistono due tipi di proprietà: ValueTypeDescriptor e StructuralTypeDescriptor.

Descrittore di tipo valore

ValueTypeDescriptor i tipi sono principalmente primitivi e vengono normalmente usati come oggetto statico.

Ecco alcuni degli elementi comuni ValueTypeDescriptor :

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

Descrittore di tipo strutturale

StructuralTypeDescriptor I tipi vengono usati principalmente per gli oggetti associati a dati. Il tipo più comune StructuralTypeDescriptor è riempimento.

export interface StructuralTypeDescriptor {
    fill?: FillTypeDescriptor;
}

Proprietà Gradient

La proprietà gradient è una proprietà che non può essere impostata come proprietà standard. È invece necessario impostare una regola per la sostituzione della proprietà selezione colori (tipo di riempimento ).

Un esempio è illustrato nel codice seguente:

"properties": {
    "showAllDataPoints": {
        "type": {
            "bool": true
        }
    },
    "fill": {
        "type": {
            "fill": {
                "solid": {
                    "color": true
                }
            }
        }
    },
    "fillRule": {
        "type": {
            "fillRule": {}
        },
        "rule": {
            "inputRole": "Gradient",
            "output": {
                "property": "fill",
                    "selector": [
                        "Category"
                    ]
            }
        }
    }
}

Prestare attenzione alle proprietà fill e fillRule . Il primo è il selettore colori e il secondo è la regola di sostituzione per la sfumatura che sostituirà la proprietà fill, visually, quando vengono soddisfatte le condizioni della regola.

Questo collegamento tra la proprietà fill e la regola di sostituzione viene impostato nella "rule">"output" sezione della proprietà fillRule .

"Rule">"InputRole" imposta quali ruoli dati attivano la regola (condizione). In questo esempio, se il ruolo "Gradient" dati contiene dati, la regola viene applicata per la "fill" proprietà .

Un esempio del ruolo dati che attiva la regola di riempimento (the last item) è illustrato nel codice seguente:

{
    "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"
            }
    ]
}

Riquadro formattazione

Per personalizzare le proprietà nel riquadro di formattazione, usare uno dei metodi seguenti, a seconda della versione dell'API in uso.

Nota

Il getFormattingModel metodo API è supportato dalle versioni API 5.1+. Per scoprire quale versione si sta usando, archiviare apiVersion il file pbiviz.json .

Per usare gli oggetti in modo efficace nell'API versione 5.1+, è necessario implementare il getFormattingModel metodo .
Questo metodo compila e restituisce un modello di formattazione che include una gerarchia completa dei riquadri delle proprietà di formattazione delle schede, dei gruppi di formattazione e contiene anche le proprietà di formattazione e i relativi valori.

Oggetti Capabilities riflessi nel modello di formattazione

Ogni proprietà di formattazione nel modello di formattazione richiede un oggetto corrispondente nel file capabilities.json . La proprietà di formattazione deve contenere un descrittore con un nome oggetto e un nome di proprietà che corrispondono esattamente all'oggetto capabilities corrispondente (i nomi di oggetto e proprietà fanno distinzione tra maiuscole e minuscole).
Ad esempio:

Per la proprietà di formattazione seguente nel modello di formattazione (vedere il contenuto dell'oggetto descrittore):

 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" }
                            }
                        }
                    }
                ],
            }],
        };

L'oggetto corrispondente della sezione capabilities objects deve essere:

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

Selettore di proprietà di formattazione

Il selettore facoltativo nel descrittore delle proprietà di formattazione determina dove ogni proprietà è associata in dataView. Sono disponibili quattro opzioni distinte.

Esempio

Nell'esempio precedente myCustomCard viene illustrato l'aspetto della proprietà di formattazione nel modello di formattazione per un oggetto con una proprietà myCustomProperty. Oggetto di proprietà associato in modo statico a dataViews[index].metadata.objects. Il selettore nel descrittore può essere modificato di conseguenza per il tipo di selettore scelto.

Tipi di selettori di oggetti

Il selettore in enumerateObjectInstances determina dove ogni oggetto è associato in dataView. Sono disponibili quattro opzioni distinte:

static

Questo oggetto è associato ai metadati dataviews[index].metadata.objects, come illustrato di seguito.

selector: null

colonne

Questo oggetto è associato a colonne con l'oggetto corrispondente QueryName.

selector: {
    metadata: 'QueryName'
}

Selettore

Questo oggetto è associato all'elemento per cui è stato creato un oggetto selectionID . In questo esempio si presuppone che siano stati creati selectionIDper alcuni punti dati e che vengano scorrere in ciclo.

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

Identità dell'ambito

Questo oggetto è associato a valori specifici all'intersezione dei gruppi. Ad esempio, se si dispone di categorie ["Jan", "Feb", "March", ...] e serie ["Small", "Medium", "Large"], potrebbe essere necessario avere un oggetto all'intersezione di valori che corrispondono Feb a e Large. A tale scopo, è possibile ottenere l'oggetto di entrambe le DataViewScopeIdentity colonne, eseguirne il push nella variabile identitiese usare questa sintassi con il selettore.

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

Contenuto correlato

Suggerimenti per incrementare le prestazioni