Share via

Objets et propriétés des visuels Power BI

  • Article

Les objets décrivent des propriétés personnalisables associées à un visuel. Un objet peut avoir plusieurs propriétés, et chaque propriété a un type associé qui décrit ce que sera la propriété. Cet article fournit des informations sur les objets et les types de propriétés.

myCustomObject est le nom interne utilisé pour référencer l’objet dans dataView.

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

Nom d’affichage et description

Notes

Le nom d'affichage et la description sont déconseillés depuis la version 5.1+ de l’API. Le nom d'affichage et la description sont maintenant ajoutés dans le modèle de mise en forme plutôt que dans le fichier capabilities.json.

displayName est le nom qui sera affiché dans le volet des propriétés. description est une description de la propriété de mise en forme qui sera présentée à l’utilisateur en tant qu’info-bulle.

Propriétés

properties est une carte des propriétés définies par le développeur.

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

Notes

show est une propriété spéciale qui permet à un commutateur de basculer l’objet.

Exemple :

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

Types de propriété

Il existe deux types de propriétés : ValueTypeDescriptor et StructuralTypeDescriptor.

Descripteur de type valeur

Les types ValueTypeDescriptor sont principalement primitifs et sont généralement utilisés comme objets statiques.

Voici quelques-uns des éléments ValueTypeDescriptor courants :

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

Descripteur de type structurel

Les types StructuralTypeDescriptor sont principalement utilisés pour les objets liés aux données. Le type StructuralTypeDescriptor le plus courant est fill.

export interface StructuralTypeDescriptor {
    fill?: FillTypeDescriptor;
}

Propriété gradient

La propriété gradient est une propriété qui ne peut pas être définie comme propriété standard. Au lieu de cela, vous devez définir une règle pour la substitution de la propriété du sélecteur de couleurs (type fill).

Le code suivant fournit un exemple :

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

Notez bien les propriétés fill et fillRule. La première est le sélecteur de couleurs, et la seconde est la règle de substitution pour le dégradé qui remplace la propriété fill, visually, quand les conditions de la règle sont remplies.

Ce lien entre la propriété fill et la règle de substitution est défini dans la section "rule">"output" de la propriété fillRule.

La propriété "Rule">"InputRole" définit le rôle de données qui déclenche la règle (condition). Dans cet exemple, si le rôle de données "Gradient" contient des données, la règle est appliquée pour la propriété "fill".

Le code suivant illustre un exemple du rôle de données qui déclenche la règle de remplissage (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"
            }
    ]
}

Volet de mise en forme

Pour personnaliser les propriétés dans le volet de mise en forme, utilisez l’une des méthodes suivantes, en fonction de la version de l’API que vous utilisez.

Notes

La méthode d’API getFormattingModel est prise en charge à partir de la version 5.1+ de l’API. Pour savoir quelle version vous utilisez, consultez le apiVersion fichier pbiviz.json .

Pour utiliser efficacement des objets dans l’API version 5.1+, vous devez implémenter la méthode getFormattingModel.
Cette méthode génère et retourne un modèle de mise en forme qui inclut la hiérarchie complète du volet de propriétés des cartes de mise en forme et des groupes de mise en forme. Elle contient également des propriétés de mise en forme et leurs valeurs.

Objets capacités reflétés dans le modèle de mise en forme

Chaque propriété de mise en forme dans le modèle de mise en forme a besoin d’un objet correspondant dans le fichier capabilities.json. La propriété de mise en forme doit contenir un descripteur avec un nom d’objet et un nom de propriété correspondant exactement à l’objet capacités associé (les noms d’objets et de propriétés respectent la casse).
Par exemple :

Pour la propriété de mise en forme suivante dans le modèle de mise en forme (voir le contenu de l’objet descripteur) :

 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’objet correspondant de la section objects des capacités doit être :

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

Sélecteur de propriété de mise en forme

Le sélecteur facultatif dans le descripteur de propriétés de mise en forme détermine où chaque propriété est liée dans le dataView. Il existe quatre options distinctes.

Exemple

L’exemple myCustomCard ci-dessus montre à quoi ressemblerait la propriété de mise en forme dans le modèle de mise en forme pour un objet avec une propriété myCustomProperty. Cet objet propriété est lié statiquement à dataViews[index].metadata.objects. Le sélecteur dans le descripteur peut être modifié en fonction du type de sélecteur que vous choisissez.

Types de sélecteurs d’objets

Le sélecteur dans enumerateObjectInstances détermine où chaque objet est lié dans le dataView. Il existe quatre options distinctes :

static

Cet objet est lié aux métadonnées dataviews[index].metadata.objects, comme illustré ici.

selector: null

colonnes

Cet objet est lié aux colonnes avec le QueryName correspondant.

selector: {
    metadata: 'QueryName'
}

selector

Cet objet est lié à l’élément pour lequel vous avez créé un selectionID. Dans cet exemple, partons du principe que nous avons créé des selectionIDs pour certains points de données, et que nous effectuons des boucles dans ceux-ci.

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

Scope identity

Cet objet est lié à des valeurs particulières à l’intersection de groupes. Par exemple, si vous avez des catégories ["Jan", "Feb", "March", ...] et des séries ["Small", "Medium", "Large"], vous souhaiterez peut-être avoir un objet à l’intersection des valeurs correspondant à Feb et Large. Pour ce faire, vous pourriez obtenir le DataViewScopeIdentity des deux colonnes, les envoyer à la variable identities et utiliser cette syntaxe avec le sélecteur.

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

Étapes suivantes

Conseils sur les performances