Tutoriel : Créer un visuel Power BI à l’aide de React

2024-10-12

En tant que développeur, vous pouvez créer vos propres visuels Power BI. Ces visuels peuvent être utilisés par vous, votre organisation ou des tiers.

Dans ce tutoriel, vous allez développer un visuel Power BI à l’aide de React. Le visuel affiche une valeur de mesure de mise en forme à l’intérieur d’un cercle. Le visuel a une taille adaptative et vous permet de personnaliser ses paramètres.

Dans ce tutoriel, vous allez apprendre à :

Créez un projet de développement pour votre visuel.
Développez votre visuel à l’aide de React.
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 React 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.

Un compte Power BI Pro ou Premium par utilisateur (PPU) . Si vous n’en avez pas, inscrivez-vous pour un essai gratuit.
Visual Studio Code (VS Code). VS Code est un environnement de développement intégré (IDE) idéal pour le développement d’applications JavaScript et TypeScript.
Windows PowerShell version 4 ou ultérieure (pour Windows). Ou Terminal (pour Mac).
Un environnement prêt pour le développement d’un visuel Power BI. Configurez votre environnement pour développer un visuel Power BI.
Ce didacticiel utilise le rapport US Sales Analysis. Vous pouvez télécharger ce rapport et le charger sur le service Power BI, ou bien utiliser votre propre rapport. Si vous avez besoin de plus d’informations sur le service Power BI et le téléchargement de fichiers, reportez-vous au didacticiel Bien démarrer avec la création dans le service Power BI.

Créer un projet de développement

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

Ouvrez PowerShell et accédez au dossier dans lequel vous souhaitez créer votre projet.
Entrez la commande suivante :
```
pbiviz new ReactCircleCard
```
Accédez au dossier du projet.
```
cd ReactCircleCard
```
Démarrez le visuel de carte ronde React. Votre visuel est maintenant exécuté tout en étant hébergé sur votre ordinateur.
```
pbiviz start
```
Important

Pour arrêter l’exécution du visuel, entrez Ctrl+C dans PowerShell et, si vous êtes invité à arrêter le traitement par lots, entrez Y, puis appuyez sur Entrée.

Afficher la carte ronde React 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.

Remarque

Avant de continuer, vérifiez que vous avez activé le mode développeur des visuels.

Connectez-vous à PowerBI.com et ouvrez le rapport US Sales Analysis.
Sélectionnez Modifier.
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.
Dans le volet Visualisations, sélectionnez Visuel de développeur.

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é.
Vérifiez qu’un visuel a été ajouté au canevas de rapport.

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.
Pendant que le nouveau visuel est sélectionné, accédez au volet Données , développez Ventes, puis sélectionnez Quantité.
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.

Configurer React dans votre projet

Dans cette rubrique, vous découvrirez comment configurer React pour votre projet visuel Power BI.

Ouvrez PowerShell et arrêtez l’exécution du visuel en entrant Ctrl + C. Lorsque vous êtes invité à arrêter le programme de traitement par lots, entrez Y, puis appuyez sur Entrée.

Installer React

Pour installer les dépendances de réaction requises, ouvrez PowerShell dans votre dossier reactCircleCard, puis exécutez la commande suivante :

npm i react react-dom

Installer les définitions de type de React

Pour installer les définitions de type pour React, ouvrez PowerShell dans votre dossier reactCircleCard et exécutez la commande suivante :

npm i @types/react @types/react-dom

Créez une classe de composant React

Procédez comme suit pour créer une classe de composant React.

Ouvrez VS code et accédez au dossier reactCircleCard.
Créez un nouveau fichier en sélectionnant Fichier>Nouveau fichier.

Copiez le code suivant dans le nouveau fichier.

import * as React from "react";

export class ReactCircleCard extends React.Component<{}>{
    render(){
        return (
            <div className="circleCard">
                Hello, React!
            </div>
        )
    }
}

export default ReactCircleCard;

Sélectionnez Enregistrer sous et accédez au dossier src.
Mettez le fichier à jour comme suit :
- Dans le champ Nom de fichier, entrez composant.
- Dans le menu déroulant Enregistrer comme type, sélectionnez TypeScript React.

Ajouter React au fichier visuel

Remplacez le code dans le fichier visual.ts par le code qui permet l’utilisation de React.

Dans le dossier src, ouvrez visual.ts et remplacez le code dans le fichier par le code suivant :

"use strict";
import powerbi from "powerbi-visuals-api";

import DataView = powerbi.DataView;
import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
import IVisual = powerbi.extensibility.visual.IVisual;

// Import React dependencies and the added component
import * as React from "react";
import * as ReactDOM from "react-dom";
import ReactCircleCard from "./component";

import "./../style/visual.less";

export class Visual implements IVisual {

    constructor(options: VisualConstructorOptions) {

    }

    public update(options: VisualUpdateOptions) {

    }
}

Notes

Par défaut, les paramètres TypeScript Power BI ne reconnaissent pas les fichiers React tsx, VS Code met en évidence component comme une erreur.

Pour restituer le composant, ajoutez l’élément HTML cible à visual.ts. Cet élément est HTMLElement dans VisualConstructorOptions, qui est passé au constructeur.

Dans le dossier src, ouvrez visual.ts.
Ajoutez le code suivant à la classe Visual :

private target: HTMLElement;
private reactRoot: React.ComponentElement<any, any>;

Ajoutez le code suivant au constructeur VisualConstructorOptions :

this.reactRoot = React.createElement(ReactCircleCard, {});
this.target = options.element;

ReactDOM.render(this.reactRoot, this.target);

Votre fichier visual.cs doit maintenant se présenter comme ceci :

"use strict";
import powerbi from "powerbi-visuals-api";

import DataView = powerbi.DataView;
import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
import IVisual = powerbi.extensibility.visual.IVisual;
import * as React from "react";
import * as ReactDOM from "react-dom";
import ReactCircleCard from "./component";    

import "./../style/visual.less";

export class Visual implements IVisual {
    private target: HTMLElement;
    private reactRoot: React.ComponentElement<any, any>;

    constructor(options: VisualConstructorOptions) {
        this.reactRoot = React.createElement(ReactCircleCard, {});
        this.target = options.element;

        ReactDOM.render(this.reactRoot, this.target);
    }

    public update(options: VisualUpdateOptions) {

    }
}

Enregistrez visual.ts.

Modifier le fichier tsconfig

Modifiez le tsconfig.json pour travailler avec React.

Dans le dossier reactCircleCard, ouvrez le fichier tsconfig.json et ajoutez deux lignes au début de l’élément compilerOptions.

"jsx": "react",
"types": ["react", "react-dom"],

Votre fichier tsconfig.json doit maintenant ressembler à ceci, et l’erreur component dans visual.ts doit être supprimée.

{
    "compilerOptions": {
        "jsx": "react",
        "types": ["react", "react-dom"],
        "allowJs": false,
        "emitDecoratorMetadata": true,
        "experimentalDecorators": true,
        "target": "es6",
        "sourceMap": true,
        "outDir": "./.tmp/build/",
        "moduleResolution": "node",
        "declaration": true,
        "lib": [
            "es2015",
            "dom"
        ]
    },
    "files": [
        "./src/visual.ts"
    ]
}

Enregistrez tsconfig.json.

Tester votre visuel

Ouvrez PowerShell dans le dossier CircleCardVisual, puis exécutez votre projet :

pbiviz start

Quand vous ajoutez un nouveau Visuel de développeur à votre rapport dans le service Power BI, il se présente comme suit :

Capture d’écran montrant le message Hello React dans le nouveau visuel de développeur créé dans le service Power BI.

Configurer le champ de données de votre visuel

Configurez le fichier de fonctionnalités de votre visuel pour qu’un seul champ de données puisse être soumis au champ de Données de mesure du visuel.

Dans VS Code, à partir du dossier reactCircleCard, ouvrez capabilities.json.
La ReactCircleCard affiche une seule valeur, Measure Data. Supprimez l’objet Category Data de dataRoles.

Après la suppression de l’objet Category Data, la clé dataRoles se présente comme suit :
```
"dataRoles": [
    {
        "displayName": "Measure Data",
        "name": "measure",
        "kind": "Measure"
    }
],
```
Supprimez tout le contenu de la clé objects (vous la remplirez plus tard).

Une fois le contenu supprimé, la clé objects se présente comme suit :
```
"objects": {},
```

Remplacez la propriété dataViewMappings par le code suivant. max: 1 dans measure spécifie qu’un seul champ de données peut être envoyé au champ de Données de mesure du visuel.

"dataViewMappings": [
    {
        "conditions": [
            {
                "measure": {
                    "max": 1
                }
            }
        ],
        "single": {
            "role": "measure"
        }
    }
]

Enregistrez les modifications que vous avez apportées à capabilities.json.
Vérifiez que pbiviz start est en cours d’exécution et, dans le service Power BI, actualisez votre visuel de carte ronde React. Le champ Données de mesure ne peut accepter qu’un seul champ de données, comme spécifié par max: 1.

Mettre à jour le style du visuel

Dans cette section, vous allez transformer la forme de votre visuel en cercle. Utilisez le fichier visual.less pour contrôler le style de votre visuel.

Dans le dossier style, ouvrez visual.less.

Remplacez le contenu de visual.less par le code suivant.

.circleCard {
    position: relative;
    box-sizing: border-box;
    border: 1px solid #000;
    border-radius: 50%;
    width: 200px;
    height: 200px;
}

p {
    text-align: center;
    line-height: 30px;
    font-size: 20px;
    font-weight: bold;

    position: relative;
    top: -30px;
    margin: 50% 0 0 0;
}

Enregistrez visual.less.

Configurez votre visuel pour recevoir des propriétés de Power BI

Dans cette section, vous allez configurer le visuel pour recevoir des données de Power BI et envoyer des mises à jour aux instances dans le fichier component.tsx.

Restituer des données à l’aide de React

Vous pouvez restituer des données à l’aide de React. Le composant peut afficher des données à partir de son propre état.

Dans VS Code, à partir du dossier reactCircleCard, ouvrez component.tsx.

Remplacez le contenu de component.tsx par le code suivant.

import * as React from "react";

export interface State {
    textLabel: string,
    textValue: string
}

export const initialState: State = {
    textLabel: "",
    textValue: ""
}

export class ReactCircleCard extends React.Component<{}, State>{
    constructor(props: any){
        super(props);
        this.state = initialState;
    }

    render(){
        const { textLabel, textValue } = this.state;

        return (
            <div className="circleCard">
                <p>
                    {textLabel}
                    <br/>
                    <em>{textValue}</em>
                </p>
            </div>
        )
    }
}

Enregistrez component.tsx.

Définir votre visuel pour recevoir des données

Les visuels reçoivent les données actuelles sous la forme d’un argument de la méthode update. Dans cette section, vous allez mettre à jour cette méthode pour recevoir des données.

Le code suivant sélectionne textLabel et textValue à partir de DataView et, si les données existent, met à jour l’état du composant.

Dans VS Code, à partir du dossier src, ouvrez visual.ts.
Remplacez la ligne import ReactCircleCard from "./component"; par le code suivant :
```
import { ReactCircleCard, initialState } from "./component";
```

Ajoutez le code suivant à la méthode update .

if(options.dataViews && options.dataViews[0]){
    const dataView: DataView = options.dataViews[0];

    ReactCircleCard.update({
        textLabel: dataView.metadata.columns[0].displayName,
        textValue: dataView.single.value.toString()
    });
} else {
    this.clear();
}

Créez une méthode clear en ajoutant le code suivant sous la méthode update.
```
private clear() {
    ReactCircleCard.update(initialState);
}
```
Enregistrez visual.ts

Définir votre visuel pour envoyer des données

Dans cette section, vous allez mettre à jour votre visuel pour envoyer des mises à jour aux instances du fichier component.

Dans VS Code, à partir du dossier src, ouvrez component.tsx.

Ajoutez le code suivant à la classe ReactCircleCard :

private static updateCallback: (data: object) => void = null;

public static update(newState: State) {
    if(typeof ReactCircleCard.updateCallback === 'function'){
        ReactCircleCard.updateCallback(newState);
    }
}

public state: State = initialState;

public componentWillMount() {
        ReactCircleCard.updateCallback = (newState: State): void => { this.setState(newState); };
}

public componentWillUnmount() {
    ReactCircleCard.updateCallback = null;
}

Enregistrez component.tsx.

Afficher les modifications apportées au visuel

Testez votre visuel de carte ronde React pour afficher les modifications que vous avez apportées.

Vérifiez que pbiviz start est en cours d’exécution et, dans le service Power BI, actualisez votre visuel de carte ronde React.
Ajoutez Ventes dans le champ de Données de mesure du visuel.

Capture d’écran de la valeur des ventes affichée dans le visuel de carte ronde React dans le service Power BI.

Rendez votre visuel redimensionnable

Actuellement, la largeur et la hauteur du composant sont fixes. Pour rendre le visuel redimensionnable, vous devez définir la variable size dans les fichiers visual.ts et component.tsx. Dans cette section, vous rendez le visuel redimensionnable.

Une fois que vous avez effectué les étapes décrites dans cette section, le diamètre du cercle dans votre visuel correspond à la largeur ou à la hauteur minimale, et vous pouvez le redimensionner dans le service Power BI.

Configurez le fichier visual.ts

Obtenez la taille actuelle de la fenêtre d’affichage du visuel à partir de l’objet options.

Dans VS Code, à partir du dossier src, ouvrez visual.ts.
Insérez ce code pour importer l’interface IViewport.
```
import IViewport = powerbi.IViewport;
```
Ajoutez la propriété viewport à la classe visual.
```
private viewport: IViewport;
```

Dans la méthode update, avant ReactCircleCard.update, ajoutez le code suivant.

this.viewport = options.viewport;
const { width, height } = this.viewport;
const size = Math.min(width, height);

Dans la méthode update, dans ReactCircleCard.update, ajoutez size.
```
size,
```
Enregistrez visual.ts.

Configurer le fichier component.tsx

Dans VS Code, à partir du dossier src, ouvrez component.tsx.
Ajoutez le code suivant à export interface State.
```
size: number
```
Ajoutez le code suivant à export const initialState: State.
```
size: 200
```
Dans la méthode render, apportez les modifications suivantes au code :
1. Ajout de size à const { textLabel, textValue, size } = this.state;. La déclaration doit maintenant ressembler à ceci :
```
const { textLabel, textValue, size } = this.state;
```
2. Ajoutez le code suivant au-dessus de return.
```
const style: React.CSSProperties = { width: size, height: size };
```
3. Remplacez la première ligne de retour<div className="circleCard"> par :
```
<div className="circleCard" style={style}>
```
Enregistrez component.tsx.

Configurez le fichier visuel

Dans VS Code, à partir du dossier style, ouvrez visual.less.
Dans .circleCard, remplacez width et height par min-width et min-height.
```
min-width: 200px;
min-height: 200px;
```
Enregistrez visual.less.

Rendre votre visuel Power BI personnalisable

Dans cette section, vous ajoutez la possibilité de personnaliser votre visuel, ce qui permet aux utilisateurs d’apporter des modifications à la couleur et l’épaisseur de la bordure.

Ajouter la couleur et l’épaisseur au fichier de fonctionnalités

Ajoutez la couleur et l’épaisseur de la bordure à la propriété object dans capabilities.json.

Dans VS Code, à partir du dossier reactCircleCard, ouvrez capabilities.json.

Ajoutez les paramètres suivants à la propriété objects.

"circle": {
    "properties": {
       "circleColor": {
            "type": {
                "fill": {
                    "solid": {
                        "color": true
                    }
                }
            }
        },
        "circleThickness": {
            "type": {
                "numeric": true
            }
        }
    }
}

Ouvrez capabilities.json.

Ajouter une classe de paramètres de mise en forme circulaire au fichier de paramètres

Ajoutez les paramètres de mise en forme Circle à settings.ts. Pour plus d’informations sur la création de paramètres de modèle de mise en forme, consultez Utilitaires de mise en forme.

Dans VS Code, à partir du dossier src, ouvrez settings.ts.

Remplacez le code de settings.ts par le code suivant :

"use strict";

import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

import FormattingSettingsCard = formattingSettings.SimpleCard;
import FormattingSettingsSlice = formattingSettings.Slice;
import FormattingSettingsModel = formattingSettings.Model;

/**
* Circle Formatting Card
*/
class CircleCardSettings extends FormattingSettingsCard {
    circleColor = new formattingSettings.ColorPicker({
        name: "circleColor", // circle color name should match circle color property name in capabilities.json
        displayName: "Color",
        description: "The fill color of the circle.",
        show: true,
        value: { value: "white" }
    });

    circleThickness = new formattingSettings.NumUpDown({
        name: "circleThickness", // circle thickness name should match circle color property name in capabilities.json
        displayName: "Thickness",
        description: "The circle thickness.",
        show: true,
        value: 2
    });

    name: string = "circle"; // circle card name should match circle object name in capabilities.json
    displayName: string = "Circle";
    show: boolean = true;
    slices: Array<FormattingSettingsSlice> = [this.circleColor, this.circleThickness];
}

/**
* visual settings model class
*
*/
export class VisualFormattingSettingsModel extends FormattingSettingsModel {
    // Create formatting settings model circle formatting card
    circleCard = new CircleCardSettings();

    cards = [this.circleCard];
}

Enregistrez settings.ts.

Ajouter une méthode pour appliquer des paramètres visuels

Ajoutez la méthode getFormattingModel utilisée pour appliquer les paramètres visuels et les importations requises dans le fichier visual.ts.

Dans VS Code, à partir du dossier src, ouvrez visual.ts.

Ajoutez ces instructions import en haut de visual.ts.

import { FormattingSettingsService } from "powerbi-visuals-utils-formattingmodel";
import { VisualFormattingSettingsModel } from "./settings";

Ajoutez la déclaration suivante à Visual.

private formattingSettings: VisualFormattingSettingsModel;
private formattingSettingsService: FormattingSettingsService;

Ajoutez la méthode getFormattingModel à Visual.

public getFormattingModel(): powerbi.visuals.FormattingModel {
    return this.formattingSettingsService.buildFormattingModel(this.formattingSettings);
}

Dans la classe Visual, ajoutez la ligne de code suivante à constructor pour initialiser formattingSettingsService
```
    this.formattingSettingsService = new FormattingSettingsService();
```

Dans la classe Visual, ajoutez le code suivant à update pour mettre à jour les paramètres de mise en forme visuelle vers les dernières valeurs des propriétés de mise en forme.

Ajoutez ce code à l’instruction si après const size = Math.min(width, height);.

this.formattingSettings = this.formattingSettingsService.populateFormattingSettingsModel(VisualFormattingSettingsModel, options.dataViews[0]);
const circleSettings = this.formattingSettings.circleCard;

Ajouter ce code à ReactCircleCard.update après size :

borderWidth: circleSettings.circleThickness.value,
background: circleSettings.circleColor.value.value,
}

Enregistrez visual.ts.

Modifier le fichier composant

Modifiez le fichier composant pour qu’il puisse restituer les modifications apportées à la couleur et l’épaisseur de la bordure du visuel.

Dans VS Code, à partir du dossier src, ouvrez component.tsx.

Ajoutez ces valeurs à State :

background?: string,
borderWidth?: number

Dans la méthode render, remplacez les lignes de code suivantes :
1. const { textLabel, textValue, size } = this.state; avec :
```
const { textLabel, textValue, size, background, borderWidth } = this.state;
```
2. const style: React.CSSProperties = { width: size, height: size }; avec :
```
const style: React.CSSProperties = { width: size, height: size, background, borderWidth };
```
Enregistrez component.tsx.

Réviser vos modifications

Expérimentez la couleur et l’épaisseur de la bordure du visuel, que vous pouvez maintenant contrôler.

Vérifiez que pbiviz start est en cours d’exécution et, dans le service Power BI, actualisez votre visuel de carte ronde React.
Sélectionnez l’onglet Format et développez Cercle.
Ajustez les paramètres de Couleur et d’Épaisseur du visuel, puis examinez leur effet sur le visuel.

Capture d’écran de la carte ronde React dans le service Power BI, montrant les options de format de couleur et d’épaisseur de bordure.

Partager via