Personnaliser le volet Mise en forme dans les visuels personnalisés Power BI
À partir de la version 5.1 de l’API, les développeurs peuvent créer des visuels qui utilisent le nouveau volet Mise en forme de Power. Les développeurs peuvent définir les cartes et leurs catégories pour n’importe quelle propriété dans leur visuel personnalisé, ce qui permet aux créateurs de rapports d’utiliser plus facilement ces visuels.
La nouvelle API utilise la méthode FormattingModel pour personnaliser des parties des volets de mise en forme et d’analyse.
Conseil
La méthode getFormattingModel remplace la méthode enumerateObjectInstances dans les versions antérieures de l’API.
getFormattingModel renvoie FormattingModel qui définit l’apparence du volet de mise en forme et d’analyse du visuel.
En plus de toutes les anciennes fonctionnalités du volet de mise en forme, le nouveau modèle de mise en forme prend en charge de nouvelles fonctionnalités, de nouvelles propriétés et de nouvelles hiérarchies du volet de mise en forme.
Pour effectuer une mise à niveau vers l’API version 5.1 ou ultérieure, définissez apiVersion dans votre fichier pbiviz.json sur 5.1 ou version ultérieure et effectuez l’une des opérations suivantes :
- Utilisez l’utilitaire formattingmodel. (Recommandé)
- Sans cet utilitaire, utilisez uniquement les API selon la méthode suivante.
Créer un visuel qui prend en charge le nouveau volet de mise en forme
Pour créer un visuel personnalisé qui utilise le nouveau volet de mise en forme :
Définissez tous les éléments personnalisables
objectsdans votre fichier capabilities.json.
Les propriétés suivantes sont requises pour chaque objet :- nom de l'objet
- nom de la propriété
- type de propriété
Toutes les autres propriétés, y compris
DisplayNameetdescription, sont désormais facultatives.Générez le visuel personnalisé FormattingModel. Définissez les propriétés de votre modèle de mise en forme de visuel personnalisé et générez-le à l’aide de code (pas JSON).
Implémentez l’API
getFormattingModeldans la classe visuelle personnalisée qui retourne un modèle de mise en forme de visuel personnalisé. (Cette API remplace leenumerateObjectInstancesqui a été utilisé dans les versions précédentes).
Propriétés de mise en forme de la carte
Si vous avez un visuel personnalisé créé avec une ancienne API et que vous souhaitez migrer vers le nouveau volet de mise en forme, ou si vous créez un visuel personnalisé :
Définissez
apiVersiondans votre fichier pbiviz.json sur5.1ou une version ultérieure.Pour chaque nom d’objet et nom de propriété dans capabilities.json, créez une propriété de mise en forme correspondante. La propriété de mise en forme doit avoir un descripteur qui contient
objectNameetpropertyNamequi correspond au nom de l’objet et au nom de la propriété dans capabilities.json.
Les propriétés objects du fichier de fonctionnalités ont toujours la même mise en forme et n’ont pas besoin d’être modifiées.
Par exemple, si l’objet circle dans votre fichier capabilities.json est défini comme suit :
"objects": {
"circle": {
"properties": {
"circleColor": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
}
}
}
La propriété de mise en forme dans votre modèle doit être de type ColorPicker et ressembler à ceci :
control: {
type: "ColorPicker",
properties: {
descriptor: {
objectName: "circle",
propertyName: "circleColor"
},
value: {
value: this.visualSettings.circle.circleColor
}
}
}
Vous obtiendrez une erreur si l’une des conditions suivantes est vraie :
- Le nom de l’objet ou de la propriété dans le fichier de fonctionnalités ne correspond pas à celui du modèle de mise en forme
- Le type de propriété dans le fichier de fonctionnalités ne correspond pas au type dans le modèle de mise en forme
Modèle de mise en forme
Le modèle de mise en forme est l’endroit où vous décrivez et personnalisez toutes les propriétés de votre volet de mise en forme.
Composants du modèle de mise en forme
Dans le nouveau modèle de mise en forme, les composants de propriété sont regroupés dans des catégories et sous-catégories logiques. Ces groupes facilitent l’analyse du modèle. Il existe cinq composants de base, du plus grand au plus petit :
Modèle de mise en forme
Le plus grand conteneur de volet, utilisé pour la mise en forme de l’interface frontale du volet. Il contient une liste de cartes de mise en forme.Carte de mise en forme
Conteneur de regroupement de propriétés de niveau supérieur pour la mise en forme des propriétés. Chaque carte se compose d’un ou plusieurs groupes de mise en forme, comme illustré ici.
Groupe de mise en forme
Conteneur de regroupement de propriétés de niveau secondaire. Le groupe de mise en forme s’affiche en tant que conteneur de regroupement pour des tranches de mise en forme.
Tranche de mise en forme
Conteneur de propriétés. Il existe deux types de tranches :- Tranche simple : conteneur de propriété individuelle
- Tranche composite : plusieurs conteneurs de propriétés connexes regroupés en une seule tranche de mise en forme
L’image suivante montre les différents types de tranches. « Police » est une tranche composite composée de la famille et de la taille de polices, et des options gras, italiques et soulignés. « Couleur », « unités d’affichage » et les autres tranches sont des tranches simples avec un composant chacune.
Propriétés de mise en forme du volet de visualisation
Chaque propriété du modèle de mise en forme doit correspondre à un type d’objet dans le fichier capabilities.json .
Le tableau suivant montre les types de propriétés de mise en forme dans le fichier capabilities.json et leur classe de type correspondante dans les propriétés du modèle de mise en forme moderne :
| Type | Type de valeur des fonctionnalités | Propriété Formatting |
|---|---|---|
| Boolean | Bool | Bouton bascule |
| Nombre | ||
| Liste d'énumération | enumeration:[] | |
| Couleur | Remplir | ColorPicker |
| Dégradé | FillRule | GradientBar : la valeur de la propriété doit être une chaîne composée de : minValue[,midValue],maxValue |
| Texte | Texte |
Objets de mise en forme des fonctionnalités
| Type | Type de valeur des fonctionnalités | Propriété Formatting |
|---|---|---|
| Taille de police | FontSize | NumUpDown |
| Famille de polices | FontFamily | FontPicker |
| Alignement de la ligne | Alignment | AlignmentGroup |
| Unités d’affichage des étiquettes | LabelDisplayUnits | AutoDropDown |
* La propriété de mise en forme de la liste d’énumération est différente dans le modèle de mise en forme et dans le fichier de fonctionnalités.
Déclarez les propriétés suivantes dans la classe des paramètres de mise en forme, y compris la liste des éléments d’énumération :
- ItemDropdown
- ItemFlagsSelection
Déclarez les propriétés suivantes dans la classe des paramètres de mise en forme, sans la liste des éléments d’énumération. Déclarez leur liste d’éléments d’énumération dans capabilities.json sous l’objet approprié. (Ces types sont les mêmes que dans les versions précédentes de l’API) :
- AutoDropdown
- AutoFlagSelection
Propriétés de tranche composite
Une tranche composite de mise en forme est une tranche de mise en forme qui contient plusieurs propriétés associées.
Pour l’instant, nous avons deux types de tranches composites :
FontControl
Ainsi, toutes les propriétés liées aux polices sont regroupées. Elle est constituée des propriétés suivantes :- Famille de polices
- Taille de police
- Gras [facultatif]
- Italique [facultatif]
- Souligné [facultatif]
Chacune de ces propriétés doit avoir un objet correspondant dans le fichier de fonctionnalités :
Propriété Type de fonctionnalités Type de mise en forme Famille de polices Mise en forme : { fontFamily} FontPicker Taille de police Mise en forme : {fontSize} NumUpDown Gras Bool Bouton bascule Italique Bool Bouton bascule Souligner Bool Bouton bascule MargePadding Le remplissage de la marge détermine l’alignement du texte dans le visuel. Elle est constituée des propriétés suivantes :
- Gauche
- Right
- Haut
- Bas
Chacune de ces propriétés doit avoir un objet correspondant dans le fichier de fonctionnalités :
Propriété Type de fonctionnalités Type de mise en forme Gauche Numérique NumUpDown Droit Numérique NumUpDown Haut Numérique NumUpDown Bas Numérique NumUpDown
Exemple : Mise en forme d’un carte de données
Dans cet exemple, nous montrons comment créer un modèle de mise en forme d’un visuel personnalisé avec une carte.
Le carte comporte deux groupes :
- Groupe de contrôle de police avec une propriété composite
- Contrôle de police
- Groupe de conception de données avec deux propriétés simples
- Couleur de police
- Alignement de la ligne
Tout d’abord, ajoutez des objets au fichier de fonctionnalités :
"objects": {
"dataCard": {
"properties": {
"displayUnitsProperty": {
"type":
{
"formatting": {
"labelDisplayUnits": true
}
}
},
"fontSize": {
"type": {
"formatting": {
"fontSize": true
}
}
},
"fontFamily": {
"type": {
"formatting": {
"fontFamily": true
}
}
},
"fontBold": {
"type": {
"bool": true
}
},
"fontUnderline": {
"type": {
"bool": true
}
},
"fontItalic": {
"type": {
"bool": true
}
},
"fontColor": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
"lineAlignment": {
"type": {
"formatting": {
"alignment": true
}
}
}
}
}
}
Ensuite, créez getFormattingModel
public getFormattingModel(): powerbi.visuals.FormattingModel {
// Building data card, We are going to add two formatting groups "Font Control Group" and "Data Design Group"
let dataCard: powerbi.visuals.FormattingCard = {
description: "Data Card Description",
displayName: "Data Card",
uid: "dataCard_uid",
groups: []
}
// Building formatting group "Font Control Group"
// Notice that "descriptor" objectName and propertyName should match capabilities object and property names
let group1_dataFont: powerbi.visuals.FormattingGroup = {
displayName: "Font Control Group",
uid: "dataCard_fontControl_group_uid",
slices: [
{
uid: "dataCard_fontControl_displayUnits_uid",
displayName:"display units",
control: {
type: powerbi.visuals.FormattingComponent.Dropdown,
properties: {
descriptor: {
objectName: "dataCard",
propertyName:"displayUnitsProperty"
},
value: 0
}
}
},
// FontControl slice is composite slice, It means it contain multiple properties inside it
{
uid: "data_font_control_slice_uid",
displayName: "Font",
control: {
type: powerbi.visuals.FormattingComponent.FontControl,
properties: {
fontFamily: {
descriptor: {
objectName: "dataCard",
propertyName: "fontFamily"
},
value: "wf_standard-font, helvetica, arial, sans-serif"
},
fontSize: {
descriptor: {
objectName: "dataCard",
propertyName: "fontSize"
},
value: 16
},
bold: {
descriptor: {
objectName: "dataCard",
propertyName: "fontBold"
},
value: false
},
italic: {
descriptor: {
objectName: "dataCard",
propertyName: "fontItalic"
},
value: false
},
underline: {
descriptor: {
objectName: "dataCard",
propertyName: "fontUnderline"
},
value: false
}
}
}
}
],
};
// Building formatting group "Font Control Group"
// Notice that "descriptor" objectName and propertyName should match capabilities object and property names
let group2_dataDesign: powerbi.visuals.FormattingGroup = {
displayName: "Data Design Group",
uid: "dataCard_dataDesign_group_uid",
slices: [
// Adding ColorPicker simple slice for font color
{
displayName: "Font Color",
uid: "dataCard_dataDesign_fontColor_slice",
control: {
type: powerbi.visuals.FormattingComponent.ColorPicker,
properties: {
descriptor:
{
objectName: "dataCard",
propertyName: "fontColor"
},
value: { value: "#01B8AA" }
}
}
},
// Adding AlignmentGroup simple slice for line alignment
{
displayName: "Line Alignment",
uid: "dataCard_dataDesign_lineAlignment_slice",
control: {
type: powerbi.visuals.FormattingComponent.AlignmentGroup,
properties: {
descriptor:
{
objectName: "dataCard",
propertyName: "lineAlignment"
},
mode: powerbi.visuals.AlignmentGroupMode.Horizonal,
value: "right"
}
}
},
]
};
// Add formatting groups to data card
dataCard.groups.push(group1_dataFont);
dataCard.groups.push(group2_dataDesign);
// Build and return formatting model with data card
const formattingModel: powerbi.visuals.FormattingModel = { cards: [dataCard] };
return formattingModel;
}
Voici le volet obtenu :
Rétablir les valeurs par défaut des paramètres
Le nouveau volet de mise en forme comporte une option pour rétablir toutes les valeurs par défaut des propriétés de la carte de mise en forme en cliquant sur le bouton Rétablir les valeurs par défaut qui apparaît dans le carte ouvert.
Pour activer cette fonctionnalité, ajoutez une liste de descripteurs de la carte de mise en forme à la carte de mise en forme revertToDefaultDescriptors.
L’exemple suivant montre comment ajouter le bouton Rétablir les valeurs par défaut :
let dataCard: powerbi.visuals.FormattingCard = {
displayName: "Data Card",
// ... card parameters and groups list
revertToDefaultDescriptors: [
{
objectName: "dataCard",
propertyName:"displayUnitsProperty"
},
{
objectName: "dataCard",
propertyName: "fontFamily"
},
// ... the rest of properties descriptors
]
};
Ajouter revertToDefaultDescriptors à la carte de mise en forme vous permet également de réinitialiser toutes les propriétés des cartes de mise en forme à la fois en cliquant sur le bouton rétablir tous les paramètres par défaut dans la barre supérieure du volet de mise en forme :
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. Découvrez-les dans les types de sélecteurs d’objets.
Localisation
Pour plus d’informations sur la fonctionnalité de localisation et pour configurer un environnement de localisation, consultez Ajouter la langue locale à votre visuel Power BI. Utilisez le gestionnaire de localisation pour mettre en forme les composants que vous souhaitez localiser :
displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");
Pour localiser les utilitaires du modèle de mise en forme, consultez Localisation des utilitaires de mise en forme.
Ressources GitHub
Toutes les interfaces de modèle de mise en forme se trouvent dans GitHub - microsoft/powerbi-visuals-api : API de visuels personnalisés Power BI dans « formatting-model-api.d.ts »
Nous vous recommandons d’utiliser les nouveaux utilitaires de modèle de mise en forme sur GitHub - microsoft/powerbi-visuals-utils-formattingmodel: utilitaires d’aide du modèle de mise en forme des visuels Power BI
Vous trouverez un exemple de visuel personnalisé SampleBarChart qui utilise l’API version 5.1.0 et implémente
getFormattingModelà l’aide des nouveaux utilitaires de modèle de mise en forme sur GitHub - microsoft/PowerBI-visuals-sampleBarChart : Visuel personnalisé de graphique à barres pour le tutoriel.
Étapes suivantes
D’autres questions ? Poser des questions à la communauté Power BI
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour