Oggetti e proprietà degli oggetti visivi di Power BI

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

myCustomObject è il nome interno usato per fare riferimento all'oggetto in dataView.

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

Nome visualizzato e descrizione

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

Proprietà

properties è una mappa delle proprietà definite dallo sviluppatore.

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

Esempio:

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

Tipi di proprietà

Esistono due tipi di proprietà: ValueTypeDescriptor e StructuralTypeDescriptor.

Descrittore di tipo valore

I tipi ValueTypeDescriptor sono principalmente primitivi e in genere vengono usati come oggetto statico.

Ecco alcuni degli elementi ValueTypeDescriptor più comuni:

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

Descrittore di tipo strutturale

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

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à di selezione del colore (tipo fill).

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. La prima è il selettore dei colori, mentre la seconda è la regola di sostituzione per la sfumatura che sostituisce la proprietà fill, visually, quando vengono soddisfatte le condizioni della regola.

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

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

Il codice seguente illustra un esempio del ruolo dati che attiva la regola di riempimento (the last item):

{
    "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 di formattazione

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

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

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

public enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
    let objectName: string = options.objectName;
    let objectEnumeration: VisualObjectInstance[] = [];

    switch( objectName ) {
        case 'myCustomObject':
            objectEnumeration.push({
                objectName: objectName,
                properties: { ... },
                selector: { ... }
            });
            break;
    };

    return objectEnumeration;
}

objectEnumeration.push({
    objectName: "customColor",
    displayName: "Custom Color",
    properties: {
        fill: {
            solid: {
                color: dataPoint.color
            }
        }
    },
    selector: null
});

Tipi di selettori di oggetti

Il selettore in enumerateObjectInstances determina la posizione in cui ogni oggetto è associato a dataView. Sono disponibili quattro opzioni diverse:

• static
• columns
• selettore
• identità dell'ambito

static

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

selector: null

colonne

Questo oggetto viene associato a colonne con QueryName corrispondente.

selector: {
    metadata: 'QueryName'
}

selector

Questo oggetto viene associato all'elemento per cui è stato creato un oggetto selectionID. In questo esempio si presuppone che siano stati creati selectionID per alcuni punti dati e di eseguire un ciclo tra di essi.

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

ScopeIdentity

Questo oggetto viene associato a valori specifici all'intersezione dei gruppi. Se, ad esempio, sono presenti categorie ["Jan", "Feb", "March", ...] e serie ["Small", "Medium", "Large"], può essere necessario un oggetto all'intersezione dei valori che corrispondono a Feb e Large. A questo scopo, è possibile ottenere il valore di DataViewScopeIdentity per entrambe le colonne, eseguirne il push alla variabile identities e usare questa sintassi con il selettore.

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

Contenuto correlato

Suggerimenti per incrementare le prestazioni