Tutoriel : Développement d’un visuel de carte ronde Power BI

Dans ce didacticiel, vous développez un visuel Power BI nommé carte ronde qui affiche une valeur de mesure mise en forme à l’intérieur d’un cercle. La carte visuelle prend en charge la personnalisation de la couleur de remplissage et de l’épaisseur du contour.

Dans ce tutoriel, vous allez apprendre à :

  • Créez un projet de développement pour votre visuel.
  • Développez votre visuel avec des éléments visuels D3.
  • Configurez votre visuel pour traiter les données.
  • Configurez votre visuel pour qu’il s’adapte aux changements de taille.
  • Configurez les paramètres de couleur adaptative et de bordure pour votre visuel.

Notes

Pour obtenir le code source complet de ce visuel, consultez Visuel de carte ronde Power BI.

Prérequis

Avant de commencer à développer votre visuel Power BI, vérifiez que vous disposez de tout ce qui est indiqué dans cette section.

Créer un projet de développement

Dans cette section, vous créez un projet pour le visuel de carte ronde.

Notes

Dans ce didacticiel, Visual Studio Code (VS Code) est utilisé pour développer le visuel Power BI.

  1. Ouvrez un nouveau terminal dans VS Code et accédez au dossier dans lequel vous souhaitez créer votre projet.

  2. Entrez la commande suivante dans le terminal PowerShell :

    pbiviz new CircleCard
    
  3. Ouvrez le dossier CircleCard dans l’Explorateur VS Code. (Fichier>Ouvrir un dossier).

    Screenshot of VS code window opened to the circle card folder.

    Pour obtenir une explication détaillée de la fonction de chacun de ces fichiers, consultez Structure de projets de visuels Power BI.

  4. Consultez la fenêtre du terminal et vérifiez que vous êtes dans le répertoire circleCard. Installez les dépendances des outils pour les visuels Power BI.

    npm install
    

    Conseil

    Pour voir quelles dépendances ont été installées dans votre visuel, consultez le fichier package.json.

  5. Démarrez le visuel de carte ronde.

    pbiviz start
    

    Votre visuel est maintenant exécuté tout en étant hébergé sur votre ordinateur.

    Important

    Ne fermez pas la fenêtre PowerShell avant la fin du tutoriel. Pour arrêter l’exécution du visuel, appuyez sur Ctrl+C et, si vous êtes invité à mettre fin au programme de traitement par lots, entrez Y, puis appuyez sur Entrer.

Voir le visuel dans le service Power BI

Pour tester le visuel dans le service Power BI, nous allons utiliser le rapport US Sales Analysis. Vous pouvez télécharger ce rapport et le charger sur le service Power BI.

Vous pouvez également utiliser votre propre rapport pour tester le visuel.

Notes

Avant de continuer, vérifiez que vous avez activé les paramètres de développeur de visuels.

  1. Connectez-vous à PowerBI.com et ouvrez le rapport US Sales Analysis.

  2. Sélectionnez Modifier.

    Screenshot of the edit option in Power B I service.

  3. Créez une nouvelle page à des fins de test en cliquant sur le bouton Nouvelle page en bas de l’interface du service Power BI.

    Screenshot of the new page button in Power B I service.

  4. Dans le volet Visualisations, sélectionnez Visuel de développeur.

    Screenshot of the developer visual in the visualizations pane.

    Ce visuel représente le visuel personnalisé que vous exécutez sur votre ordinateur. Il n’est disponible que lorsque le paramètre débogage de visuel personnalisé est activé.

  5. Vérifiez qu’un visuel a été ajouté au canevas de rapport.

    Screenshot of the new visual added to the report.

    Il s’agit d’un visuel simple qui affiche le nombre de fois où sa méthode de mise à jour a été appelée. À ce stade, le visuel ne récupère aucune donnée.

    Notes

    Si le visuel affiche un message d’erreur de connexion, ouvrez un nouvel onglet dans votre navigateur, accédez à https://localhost:8080/assets et autorisez votre navigateur à utiliser cette adresse.

    Screenshot of the new visual displaying a connection error.

  6. Lorsque le nouveau visuel est sélectionné, accédez au volet Champs, développez Sales, puis sélectionnez Quantity.

    Screenshot of the Power B I service quantity field in the sales table in the U S sales analysis report.

  7. Pour tester la réponse du visuel, redimensionnez-le et remarquez que le Nombre de mises à jour est incrémenté chaque fois que vous redimensionnez le visuel.

    Screenshot of the new visual displaying a different update count number, after being resized.

Ajouter des éléments visuels et du texte

Dans cette section, vous apprenez à transformer votre visuel en cercle et à lui faire afficher du texte.

Modifier le fichier de visuels

Configurez le fichier visual.ts.

Conseil

Pour améliorer la lisibilité, il est recommandé de mettre en forme le document chaque fois que vous copiez des extraits de code dans votre projet. Effectuez un clic droit n’importe où dans VS Code, puis sélectionnez Mettre en forme le document (ou saisissez Alt+Shift+F).

  1. Dans VS Code, dans le volet Explorer, développez le dossier src, puis sélectionnez le fichier visual.ts.

    Screenshot of accessing the visual.ts file in V S code.

  2. Supprimez tout le code sous le commentaire de licence MIT.

    Important

    Notez les commentaires en haut du fichier visual.ts. L’utilisation gratuite des packages de visuels Power BI est autorisée conformément aux termes du contrat de licence MIT (Massachusetts Institute of Technology). Dans le cadre du contrat, vous devez laisser les commentaires en haut du fichier.

  3. Importez les bibliothèques et les modules nécessaires, puis définissez la sélection du type pour la bibliothèque d3 :

    "use strict";
    
    import "./../style/visual.less";
    import powerbi from "powerbi-visuals-api";
    import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;
    import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
    import IVisual = powerbi.extensibility.visual.IVisual;
    import DataView = powerbi.DataView;
    import IVisualHost = powerbi.extensibility.IVisualHost;
    import * as d3 from "d3";
    type Selection<T extends d3.BaseType> = d3.Selection<T, any, any, any>;
    

    Notes

    Si la bibliothèque JavaScript D3 n’a pas été installée dans le cadre de votre installation, installez-la maintenant. À partir de PowerShell, exécutez npm i d3@latest --save

    Parmi les éléments que vous avez importés figurent :

    • IVisualHost : une collection de propriétés et de services utilisés pour interagir avec l’hôte visuel (Power BI).
    • Bibliothèque D3 : bibliothèque JavaScript pour la création de documents pilotés par les données.
  4. Sous les importations, créez une classe visuel vide. La classe visuel implémente l’interface IVisual où tous les visuels commencent :

    export class Visual implements IVisual {
    
    }
    

    Pour plus d’informations sur les éléments de la classe « visuel », consultez API Visuel. Dans les trois étapes suivantes, nous allons définir cette classe.

  5. Ajoutez des méthodes privées au niveau de la classe au début de la classe visuel :

    private host: IVisualHost;
    private svg: Selection<SVGElement>;
    private container: Selection<SVGElement>;
    private circle: Selection<SVGElement>;
    private textValue: Selection<SVGElement>;
    private textLabel: Selection<SVGElement>;
    

    Certaines de ces méthodes privées utilisent le type Sélection.

  6. Définissez les éléments de cercle et de texte dans la méthode du constructeur. Cette méthode est appelée lorsque le visuel est instancié. Les graphiques SVG (Scalable Vector Graphics) D3 permettent de créer trois formes : un cercle et deux éléments de texte :

    constructor(options: VisualConstructorOptions) {
        this.svg = d3.select(options.element)
            .append('svg')
            .classed('circleCard', true);
        this.container = this.svg.append("g")
            .classed('container', true);
        this.circle = this.container.append("circle")
            .classed('circle', true);
        this.textValue = this.container.append("text")
            .classed("textValue", true);
        this.textLabel = this.container.append("text")
            .classed("textLabel", true);
    }
    
  7. Définissez la largeur et la hauteur dans la méthode de mise à jour. Cette méthode est appelée chaque fois qu’une modification est apportée aux données ou à l’environnement hôte, comme une nouvelle valeur ou un redimensionnement.

    public update(options: VisualUpdateOptions) {
        let width: number = options.viewport.width;
        let height: number = options.viewport.height;
        this.svg.attr("width", width);
        this.svg.attr("height", height);
        let radius: number = Math.min(width, height) / 2.2;
        this.circle
            .style("fill", "white")
            .style("fill-opacity", 0.5)
            .style("stroke", "black")
            .style("stroke-width", 2)
            .attr("r", radius)
            .attr("cx", width / 2)
            .attr("cy", height / 2);
        let fontSizeValue: number = Math.min(width, height) / 5;
        this.textValue
            .text("Value")
            .attr("x", "50%")
            .attr("y", "50%")
            .attr("dy", "0.35em")
            .attr("text-anchor", "middle")
            .style("font-size", fontSizeValue + "px");
        let fontSizeLabel: number = fontSizeValue / 4;
        this.textLabel
            .text("Label")
            .attr("x", "50%")
            .attr("y", height / 2)
            .attr("dy", fontSizeValue / 1.2)
            .attr("text-anchor", "middle")
            .style("font-size", fontSizeLabel + "px");
    }
    
  8. Enregistrez le fichier visual.ts.

(Facultatif) Examiner le code dans le fichier de visuels

Vérifiez que le code final du fichier visual.ts est semblable à ceci :

/*
*  Power BI Visual CLI
*
*  Copyright (c) Microsoft Corporation
*  All rights reserved.
*  MIT License
*
*  Permission is hereby granted, free of charge, to any person obtaining a copy
*  of this software and associated documentation files (the ""Software""), to deal
*  in the Software without restriction, including without limitation the rights
*  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
*  copies of the Software, and to permit persons to whom the Software is
*  furnished to do so, subject to the following conditions:
*
*  The above copyright notice and this permission notice shall be included in
*  all copies or substantial portions of the Software.
*
*  THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
*  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
*  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
*  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
*  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
*  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
*  THE SOFTWARE.
*/
"use strict";

import "./../style/visual.less";
import powerbi from "powerbi-visuals-api";
import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
import IVisual = powerbi.extensibility.visual.IVisual;
import DataView = powerbi.DataView;
import IVisualHost = powerbi.extensibility.IVisualHost;
import * as d3 from "d3";
type Selection<T extends d3.BaseType> = d3.Selection<T, any, any, any>;

export class Visual implements IVisual {
    private host: IVisualHost;
    private svg: Selection<SVGElement>;
    private container: Selection<SVGElement>;
    private circle: Selection<SVGElement>;
    private textValue: Selection<SVGElement>;
    private textLabel: Selection<SVGElement>;
    
    constructor(options: VisualConstructorOptions) {
        this.svg = d3.select(options.element)
            .append('svg')
            .classed('circleCard', true);
        this.container = this.svg.append("g")
            .classed('container', true);
        this.circle = this.container.append("circle")
            .classed('circle', true);
        this.textValue = this.container.append("text")
            .classed("textValue", true);
        this.textLabel = this.container.append("text")
            .classed("textLabel", true);
    }
    
    public update(options: VisualUpdateOptions) {
        let width: number = options.viewport.width;
        let height: number = options.viewport.height;
        this.svg.attr("width", width);
        this.svg.attr("height", height);
        let radius: number = Math.min(width, height) / 2.2;
        this.circle
            .style("fill", "white")
            .style("fill-opacity", 0.5)
            .style("stroke", "black")
            .style("stroke-width", 2)
            .attr("r", radius)
            .attr("cx", width / 2)
            .attr("cy", height / 2);
        let fontSizeValue: number = Math.min(width, height) / 5;
        this.textValue
            .text("Value")
            .attr("x", "50%")
            .attr("y", "50%")
            .attr("dy", "0.35em")
            .attr("text-anchor", "middle")
            .style("font-size", fontSizeValue + "px");
        let fontSizeLabel: number = fontSizeValue / 4;
        this.textLabel
            .text("Label")
            .attr("x", "50%")
            .attr("y", height / 2)
            .attr("dy", fontSizeValue / 1.2)
            .attr("text-anchor", "middle")
            .style("font-size", fontSizeLabel + "px");
    }
}

Modifier le fichier de fonctionnalités

Le visuel de carte ronde est un visuel simple qui ne crée aucun objet dans le volet Format. Par conséquent, vous pouvez supprimer en toute sécurité la section objets du fichier.

  1. Ouvrez votre projet dans VS Code (Fichier>Ouvrir le dossier).

  2. Sélectionnez le fichier capabilities.json.

    Screenshot of accessing the capabilities.json file in V S code.

  3. Supprimez l’intégralité du tableau d’objets.
    Ne laissez pas de lignes vides entre dataRoles et dataViewMappings.

  4. Enregistrez le fichier capabilities.json.

Redémarrer le visuel de carte ronde

Arrêtez l’exécution du visuel et redémarrez-le.

  1. Dans la fenêtre PowerShell où vous avez démarré le visuel, appuyez sur Ctrl+C. Lorsque vous êtes invité à arrêter le programme de traitement par lots, entrez Y et appuyez sur Entrer.

  2. Dans PowerShell, redémarrez le visuel.

    pbiviz start
    

Tester le visuel avec les éléments ajoutés

Vérifiez que le visuel affiche les éléments qui viennent d’être ajoutés.

  1. Dans le service Power BI, ouvrez le rapport Power BI US Sales Analysis. Si vous utilisez un autre rapport pour développer le visuel de carte ronde, accédez à ce rapport.

  2. Faites glisser une valeur dans la zone Mesure et assurez-vous que le visuel est en forme de cercle.

    Screenshot of the circle card visual shaped as a circle.

    Si le visuel n’affiche rien, à partir du volet Champs, faites glisser le champ Quantité dans le visuel de développeur.

  3. Redimensionnez le visuel.

    Notez que le cercle et le texte s’adaptent aux dimensions du visuel. La méthode update est appelée lorsque vous redimensionnez le visuel et, par conséquent, les visuels sont redimensionnés.

Activer le rechargement automatique

Utilisez ce paramètre pour garantir que le visuel est rechargé automatiquement chaque fois que vous enregistrez des modifications apportées au projet.

  1. Accédez au rapport Power BI US Sales Analysis (ou au projet qui contient votre visuel de carte ronde).

  2. Sélectionnez le visuel de carte ronde.

  3. Dans la barre d’outils flottante, sélectionnez Activer/désactiver le rechargement automatique.

    Screenshot of clicking the toggle auto reload option, in the circle card visual floating toolbar.

Obtenir le visuel pour traiter les données

Dans cette section, vous définissez des rôles de données et des mappages de vues de données. Vous allez également modifier le visuel pour afficher le nom de la valeur qu’il affiche.

Configurer le fichier de fonctionnalités

Modifiez le fichier capabilities.json pour définir le rôle des données et les mappages de vues de données.

  • Définir le rôle des données

    Définissez le tableau dataRoles avec un seul rôle de données de type mesure. Ce rôle de données est appelé mesure et s’affiche sous la forme Measure. Il permet de transmettre soit un champ de mesure, soit un champ résumé.

    1. Ouvrez le fichier capabilities.json dans VS Code.

    2. Supprimez tout le contenu à l’intérieur du tableau dataRoles.

    3. À l’intérieur du tableau dataRoles, insérez le code suivant.

      {
          "displayName": "Measure",
          "name": "measure",
          "kind": "Measure"
      }
      
    4. Enregistrez le fichier capabilities.json.

  • Définir le mappage de vues de données

    Définissez un champ nommé measure dans le tableau dataViewMappings. Ce champ peut être passé au rôle de données.

    1. Ouvrez le fichier capabilities.json dans VS Code.

    2. Supprimez tout le contenu à l’intérieur du tableau dataViewMappings.

    3. Insérez le code suivant dans le tableau dataViewMappings.

      {
          "conditions": [
              { "measure": { "max": 1 } }
          ],
          "single": {
              "role": "measure"
          }
      }
      
    4. Enregistrez le fichier capabilities.json.

Vérifiez que votre fichier capabilities.json ressemble à ceci :

{
    "dataRoles": [
        {
            "displayName": "Measure",
            "name": "measure",
            "kind": "Measure"
        }
    ],
    "dataViewMappings": [
        {
            "conditions": [
                { "measure": { "max": 1 } }
            ],
            "single": {
                "role": "measure"
            }
        }
    ],
    "privileges": []
}

(Facultatif) Passer en revue les modifications du code du fichier de fonctionnalités

Vérifiez que le visuel de carte ronde affiche le champ measure et passez en revue les modifications que vous avez apportées à l’aide de l’option Afficher le DataView.

  1. Dans le service Power BI, ouvrez le rapport Power BI US Sales Analysis. Si vous utilisez un autre rapport pour développer le visuel de carte ronde, accédez à ce rapport.

  2. Notez que le visuel de carte ronde peut maintenant être configuré avec un champ intitulé measure. Vous pouvez déposer des éléments à partir du volet Champs dans le champ Measure.

    Screenshot of the circle card measure filed, in the Power BI service visualization pane.

    Remarque

    Le projet de visuel n’inclut pas encore la logique de liaison de données.

  3. Dans la barre d’outils flottante, sélectionnez Afficher le Dataview.

    Screenshot of the show dataview button, located in the circle card floating toolbar.

  4. Sélectionnez les trois points pour développer l’affichage et sélectionnez unique pour afficher la valeur.

    Screenshot of the value figure as it's displayed in the circle card show dataview option.

  5. Développez metadata, puis le tableau columns et passez en revue les valeurs format et displayName.

    Screenshot of the format and display name values as displayed in the circle card show dataview option.

  6. Pour revenir au visuel, dans la barre d’outils flottante au-dessus du visuel, sélectionnez Afficher le Dataview.

Configurer le visuel pour consommer des données

Jusqu’ici, le visuel s’affiche, mais ne présente aucune donnée. Dans cette section, vous apportez des modifications au fichier visual.ts, afin que le visuel de carte ronde puisse consommer des données.

  1. Ouvrez le fichier visual.ts dans VS Code.

  2. Dans la méthode de mise à jour :

    • Ajoutez l’instruction suivante en tant que première instruction. L’instruction assigne dataView à une variable pour un accès facile et déclare la variable pour référencer l’objet dataView.

      let dataView: DataView = options.dataViews[0];
      
    • Remplacez .text("Value") par la ligne de code suivante :

      .text(<string>dataView.single.value)
      
    • Remplacez .text("Label") par la ligne de code suivante :

      .text(dataView.metadata.columns[0].displayName)
      
  3. Enregistrez le fichier visual.ts.

  4. Passez en revue le visuel dans le service Power BI.

Le visuel affiche maintenant le nom et la valeur du champ de données sélectionné.

Screenshot of a circle card visual displaying the quantity value.

Vous avez maintenant créé un visuel Power BI fonctionnel. Vous pouvez y Ajouter des options de mise en forme, ou vous pouvez l’empaqueter en l’état pour une utilisation immédiate.

Étapes suivantes