Objekte und Eigenschaften von Power BI-Visuals

  • Artikel

Objekte beschreiben anpassbare Eigenschaften, die einem Visual zugeordnet sind. Ein Objekt kann mehrere Eigenschaften aufweisen, und jede Eigenschaft verfügt über einen zugehörigen Typ, der beschreibt, was die Eigenschaft sein wird. In diesem Artikel werden Informationen zu Objekten und Eigenschaftstypen bereitgestellt.

myCustomObject ist der interne Name, mit dem auf das Objekt in dataView verwiesen wird.

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

Anzeigename und Beschreibung

Hinweis

Anzeigename und Beschreibung sind ab API-Version 5.1 und höher veraltet. Der Anzeigename und die Beschreibung werden jetzt im Formatierungsmodell anstelle der Datei capabilities.json hinzugefügt.

displayName ist der Name, der im Eigenschaftenbereich angezeigt wird. description ist eine Beschreibung der Formatierungseigenschaft, die dem Benutzer als QuickInfo angezeigt wird.

Eigenschaften

properties ist eine Zuordnung von Eigenschaften, die vom Entwickler definiert wurden.

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

Hinweis

show ist eine spezielle Eigenschaft, die einen Schalter zum Ein-/Ausschalten des Objekts aktiviert.

Beispiel:

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

Eigenschaftentypen

Es gibt zwei Eigenschaftentypen: ValueTypeDescriptor und StructuralTypeDescriptor.

ValueTypeDescriptor

ValueTypeDescriptor-Typen sind meistens primitiv und werden in der Regel als statische Objekte verwendet.

Es folgen einige allgemeine ValueTypeDescriptor-Elemente:

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

StructuralTypeDescriptor

StructuralTypeDescriptor-Typen werden meistens für datengebundene Objekte verwendet. Der gängigste StructuralTypeDescriptor-Typ ist fill.

export interface StructuralTypeDescriptor {
    fill?: FillTypeDescriptor;
}

Gradient-Eigenschaft

Die Gradient-Eigenschaft kann nicht als Standardeigenschaft festgelegt werden. Stattdessen müssen Sie eine Regel für die Ersetzung der Farbauswahleigenschaft (fill-Typ) festlegen.

Im folgenden Code wird ein Beispiel dafür veranschaulicht:

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

Achten Sie auf die Eigenschaften fill und fillRule. Die erste Eigenschaft ist die Farbauswahl und die zweite ist die Ersetzungsregel für den Farbverlauf, der die fill-Eigenschaftvisually ersetzt, wenn die Bedingungen der Regel erfüllt werden.

Die Verknüpfung zwischen der fill-Eigenschaft und der Ersetzungsregel wird im Abschnitt "rule">"output" der fillRule-Eigenschaft festgelegt.

Die "Rule">"InputRole"-Eigenschaft legt fest, durch welche Datenrolle die Regel (Bedingung) ausgelöst wird. Wenn die "Gradient"-Datenrolle in diesem Beispiel die Daten enthält, wird die Regel auf die "fill"-Eigenschaft angewendet.

Im folgenden Code sehen Sie ein Beispiel für die Datenrolle, die die Füllregel auslöst (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"
            }
    ]
}

Formatierungsbereich

Um die Eigenschaften im Formatierungsbereich anzupassen, verwenden Sie eine der folgenden Methoden, je nachdem, welche API-Version Sie verwenden.

Hinweis

Die API-Methode getFormattingModel wird ab API-Versionen 5.1 und höher unterstützt. Um herauszufinden, welche Version Sie verwenden, überprüfen Sie die apiVersion in der Datei pbiviz.json.

Um Objekte in API-Version 5.1 und höher effektiv verwenden zu können, müssen Sie die getFormattingModel-Methode implementieren.
Diese Methode erstellt und gibt ein Formatierungsmodell zurück, das die vollständige Eigenschaftenbereichshierarchie von Formatierungskarten, Formatierungsgruppen und auch Formatierungseigenschaften und deren Werte enthält.

Funktionenobjekte, die im Formatierungsmodell reflektiert werden

Jede Formatierungseigenschaft im Formatierungsmodell benötigt ein entsprechendes Objekt in der Datei capabilities.json. Die Formatierungseigenschaft sollte einen Deskriptor mit einem Objektnamen und Eigenschaftennamen enthalten, die genau mit dem entsprechenden Funktionenobjekt übereinstimmen (bei den Objekt- und Eigenschaftsnamen wird die Groß-/Kleinschreibung beachtet).
Beispiel:

Die folgende Formatierungseigenschaft im Formatierungsmodell (siehe Deskriptorobjektinhalt):

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

Das entsprechende Objekt aus dem Abschnitt „Funktionen objects“ sollte Folgendes sein:

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

Formatieren von Eigenschaftenauswahl

Die optionale Auswahl im Deskriptor für Formatierungseigenschaften bestimmt, wo die einzelnen Eigenschaften in der dataView gebunden sind. Es gibt vier verschiedene Optionen.

Beispiel

Das obige Beispiel myCustomCard zeigt, wie die Formatierungseigenschaft im Formatierungsmodell für ein Objekt mit einer Eigenschaft myCustomProperty aussehen würde. Dieses Eigenschaftsobjekt ist statisch an dataViews[index].metadata.objects gebunden. Die Auswahl im Deskriptor kann entsprechend dem Auswahltyp geändert werden.

Objektauswahltypen

Der Selektor in enumerateObjectInstances bestimmt, wo die einzelnen Objekte in dataView gebunden sind. Es gibt vier verschiedene Optionen:

static

Dieses Objekt wird wie hier gezeigt an dataviews[index].metadata.objects-Metadaten gebunden.

selector: null

Spalten

Dieses Objekt wird an Spalten mit entsprechendem QueryName gebunden.

selector: {
    metadata: 'QueryName'
}

selector

Dieses Objekt wird an das Element gebunden, für das Sie selectionID erstellt haben. In diesem Beispiel wird davon ausgegangen, dass Sie selectionIDs für einige Datenpunkte erstellt haben und diese in einer Schleife durchlaufen.

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

ScopeIdentity

Dieses Objekt wird am Schnittpunkt von Gruppen an bestimmte Werte gebunden. Wenn Sie beispielsweise über die Kategorien ["Jan", "Feb", "March", ...] und die Reihe ["Small", "Medium", "Large"] verfügen, möchten Sie möglicherweise über ein Objekt am Schnittpunkt der Werte verfügen, die mit Feb und Large übereinstimmen. Hierzu könnten Sie die DataViewScopeIdentity-Eigenschaft beider Spalten abrufen, diese an die Variable identities pushen und diese Syntax mit dem Selektor verwenden.

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

Nächste Schritte

Leistungstipps