Utilitaires pour les couleurs

2024-01-13

Cet article va vous aider à installer, à importer et à utiliser les utilitaires pour les couleurs. Découvrez comment utiliser des utilitaires de couleurs pour appliquer des thèmes et des palettes aux points de données d’un visuel Power BI.

Prérequis

Pour utiliser le package, installez :

node.js (nous vous recommandons de télécharger la version la plus récente de LTS)
npm (la version la plus ancienne prise en charge est 3.0.0)
Le visuel personnalisé créé par PowerBI-visuals-tools

Installation

Pour installer le package, vous devez exécuter la commande suivante dans le répertoire contenant votre visuel actuel :

npm install powerbi-visuals-utils-colorutils --save

Cette commande installe le package et ajoute un package à votre fichier package.json en tant que dépendance.

Usage

Pour utiliser les utilitaires d’interactivité, vous devez importer le composant requis dans le code source du visuel.

import { ColorHelper } from "powerbi-visuals-utils-colorutils";

Découvrez comment installer et utiliser colorUtils dans vos visuels Power BI :

[Guide d’utilisation] Le guide d’utilisation décrit une API publique du package. Il fournit une description et des exemples pour chaque interface publique.

Ce package contient les classes et modules suivants :

ColorHelper : aide à générer des couleurs différentes pour les valeurs de votre graphique
colorUtils : aide à la conversion des formats de couleurs

ColorHelper

La classe ColorHelper fournit les fonctions et méthodes suivantes :

getColorForSeriesValue

Cette méthode obtient la couleur pour une valeur de série spécifique. Si aucune couleur explicite ou couleur par défaut n’a été définie, la couleur est attribuée à partir de l’échelle de couleurs pour cette série.

getColorForSeriesValue(objects: IDataViewObjects, value: PrimitiveValue, themeColorName?: ThemeColorName): string;

getColorForSeriesValue example

import powerbi from "powerbi-visuals-api";
import { ColorHelper } from "powerbi-visuals-utils-colorutils";

import DataViewObjects = powerbi.DataViewObjects;

import DataViewValueColumns = powerbi.DataViewValueColumns;
import DataViewValueColumnGroup = powerbi.DataViewValueColumnGroup;
import DataViewObjectPropertyIdentifier = powerbi.DataViewObjectPropertyIdentifier;

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

export class YourVisual implements IVisual {
    // Implementation of IVisual

    private colorPalette: IColorPalette;

    constructor(options: VisualConstructorOptions) {
        this.colorPalette = options.host.colorPalette;
    }

    public update(visualUpdateOptions: VisualUpdateOptions): void {
        const valueColumns: DataViewValueColumns = visualUpdateOptions.dataViews[0].categorical.values,
            grouped: DataViewValueColumnGroup[] = valueColumns.grouped(),
            defaultDataPointColor: string = "green",
            fillProp: DataViewObjectPropertyIdentifier = {
                objectName: "objectName",
                propertyName: "propertyName"
            };

        let colorHelper: ColorHelper = new ColorHelper(
            this.colorPalette,
            fillProp,
            defaultDataPointColor);

        for (let i = 0; i < grouped.length; i++) {
            let grouping: DataViewValueColumnGroup = grouped[i];

            let color = colorHelper.getColorForSeriesValue(grouping.objects, grouping.name); // returns a color of the series
        }
    }
}

getColorForMeasure

Cette méthode obtient la couleur pour une valeur de série spécifique.

 getColorForMeasure(objects: IDataViewObjects, measureKey: any, themeColorName?: ThemeColorName): string;

Obtenir la couleur pour l’exemple de mesure

import powerbi from "powerbi-visuals-api";
import { ColorHelper } from "powerbi-visuals-utils-colorutils";

import DataViewObjects = powerbi.DataViewObjects;
import IVisual = powerbi.extensibility.visual.IVisual;
import IColorPalette = powerbi.extensibility.IColorPalette;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
import DataViewObjectPropertyIdentifier = powerbi.DataViewObjectPropertyIdentifier;
import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;

export class YourVisual implements IVisual {
    // Implementation of IVisual

    private colorPalette: IColorPalette;

    constructor(options: VisualConstructorOptions) {
        this.colorPalette = options.host.colorPalette;
    }

    public update(visualUpdateOptions: VisualUpdateOptions): void {
        const objects: DataViewObjects = visualUpdateOptions.dataViews[0].categorical.categories[0].objects[0],
            defaultDataPointColor: string = "green",
            fillProp: DataViewObjectPropertyIdentifier = {
                objectName: "objectName",
                propertyName: "propertyName"
            };

        let colorHelper: ColorHelper = new ColorHelper(
            this.colorPalette,
            fillProp,
            defaultDataPointColor);

        let color = colorHelper.getColorForMeasure(objects, ""); // returns a color
    }
}

`normalizeSelector` statique

Cette méthode retourne le sélecteur normalisé

static normalizeSelector(selector: Selector, isSingleSeries?: boolean): Selector;

exemple de normalizeSelector statique

import ISelectionId = powerbi.visuals.ISelectionId;
import { ColorHelper } from "powerbi-visuals-utils-colorutils";

let selectionId: ISelectionId = ...;
let selector = ColorHelper.normalizeSelector(selectionId.getSelector(), false);

Les méthodes getThemeColor et getHighContrastColor sont toutes deux liées aux couleurs du thème de couleur. ColorHelper a la propriété isHighContrast.

`getThemeColor`

Cette méthode retourne la couleur du thème.

 getThemeColor(themeColorName?: ThemeColorName): string;

`getHighContrastColor`

Cette méthode retourne la couleur pour le mode de contraste élevé.

getHighContrastColor(themeColorName?: ThemeColorName, defaultColor?: string): string;

Exemple de mode à contraste élevé


import { ColorHelper } from "powerbi-visuals-utils-colorutils";

export class MyVisual implements IVisual {
        private colorHelper: ColorHelper;

        private init(options: VisualConstructorOptions): void {
            this.colors = options.host.colorPalette;
            this.colorHelper = new ColorHelper(this.colors);
        } 

            private createViewport(element: HTMLElement): void {
                const fontColor: string = "#131aea";
                const axisBackgroundColor: string = this.colorHelper.getThemeColor();
                
                // some d3 code before
                d3ElementName.attr("fill", colorHelper.getHighContrastColor("foreground", fontColor);
            }
                
            public static parseSettings(dataView: DataView, colorHelper: ColorHelper): VisualSettings {
                // some code that should be applied on formatting settings
                if (colorHelper.isHighContrast) {
                        this.settings.fontColor = colorHelper.getHighContrastColor("foreground", this.settings.fontColor);
                    }
            }
}

`ColorUtils`

Le module fournit les fonctions suivantes :

hexToRGBString
rotate
parseColorString
calculateHighlightColor
createLinearColorScale
shadeColor
rgbBlend
channelBlend
hexBlend

hexToRGBString

Convertit une couleur hexadécimale en chaîne RVB.

function hexToRGBString(hex: string, transparency?: number): string

exemple hexToRGBString

import  { hexToRGBString } from "powerbi-visuals-utils-colorutils";

hexToRGBString('#112233');

// returns: "rgb(17,34,51)"

rotate

Fait pivoter la couleur RVB.

function rotate(rgbString: string, rotateFactor: number): string

exemple de rotation

import { rotate } from "powerbi-visuals-utils-colorutils";

rotate("#CC0000", 0.25); // returns: #66CC00

parseColorString

Analyse toute chaîne de couleur au format RVB.

function parseColorString(color: string): RgbColor

parseColorString example

import { parseColorString } from "powerbi-visuals-utils-colorutils";

parseColorString('#09f');
// returns: {R: 0, G: 153, B: 255 }

parseColorString('rgba(1, 2, 3, 1.0)');
// returns: {R: 1, G: 2, B: 3, A: 1.0 }

calculateHighlightColor

Calcule la couleur de surbrillance à partir de rgbColor en fonction de lumianceThreshold et delta.

function calculateHighlightColor(rgbColor: RgbColor, lumianceThreshold: number, delta: number): string

exemple calculateHighlightColor

import { calculateHighlightColor } from "powerbi-visuals-utils-colorutils";

let yellow = "#FFFF00",
    yellowRGB = parseColorString(yellow);

calculateHighlightColor(yellowRGB, 0.8, 0.2);

// returns: '#CCCC00'

createLinearColorScale

Retourne une échelle de couleurs linéaire pour un domaine de nombres spécifique.

function createLinearColorScale(domain: number[], range: string[], clamp: boolean): LinearColorScale

exemple createLinearColorScale

import { createLinearColorScale } from "powerbi-visuals-utils-colorutils";

let scale = ColorUtility.createLinearColorScale(
    [0, 1, 2, 3, 4],
    ["red", "green", "blue", "black", "yellow"],
    true);

scale(1); // returns: green
scale(10); // returns: yellow

shadeColor

Convertit une expression hexadécimale de chaîne en nombre, calcule le pourcentage et les canaux R, V, B. Applique le pourcentage pour chaque canal et retourne la valeur hexadécimale sous la forme d’une chaîne avec le signe dièse.

function shadeColor(color: string, percent: number): string

exemple shadeColor

import { shadeColor } from "powerbi-visuals-utils-colorutils";

shadeColor('#000000', 0.1); // returns '#1a1a1a'
shadeColor('#FFFFFF', -0.5); // returns '#808080'
shadeColor('#00B8AA', -0.25); // returns '#008a80'
shadeColor('#00B8AA', 0); // returns '#00b8aa'

rgbBlend

Superpose une couleur avec opacité sur une couleur d’arrière-plan. Tout canal alpha est ignoré.

function rgbBlend(foreColor: RgbColor, opacity: number, backColor: RgbColor): RgbColor

exemple rgbBlend

import { rgbBlend} from "powerbi-visuals-utils-colorutils";

rgbBlend({R: 100, G: 100, B: 100}, 0.5, {R: 200, G: 200, B: 200});

// returns: {R: 150, G: 150, B: 150}

channelBlend

Fusionne un canal unique pour deux couleurs.

function channelBlend(foreChannel: number, opacity: number, backChannel: number): number

exemple channelBlend

import { channelBlend} from "powerbi-visuals-utils-colorutils";

channelBlend(0, 1, 255); // returns: 0
channelBlend(128, 1, 255); // returns: 128
channelBlend(255, 0, 0); // returns: 0
channelBlend(88, 0, 88); // returns: 88

hexBlend

Superpose une couleur avec opacité sur une couleur d’arrière-plan.

function hexBlend(foreColor: string, opacity: number, backColor: string): string

exemple hexBlend

import { hexBlend} from "powerbi-visuals-utils-colorutils";

let yellow = "#FFFF00",
    black = "#000000",
    white = "#FFFFFF";

hexBlend(yellow, 0.5, white); // returns: "#FFFF80"
hexBlend(white, 0.5, yellow); // returns: "#FFFF80"

hexBlend(yellow, 0.5, black); // returns: "#808000"
hexBlend(black, 0.5, yellow); // returns: "#808000"