Utilitaires de mise en forme

Les utilitaires de mise en forme contiennent les classes, les interfaces et les méthodes pour mettre en forme des valeurs. Ils contiennent également des méthodes d’extendeur pour traiter des chaînes et mesurer la taille du texte dans un document SVG/HTML.

Service de mesure du texte

Le module fournit les fonctions et interfaces suivantes :

Interface TextProperties

Cette interface décrit les propriétés communes du texte.

interface TextProperties {
    text?: string;
    fontFamily: string;
    fontSize: string;
    fontWeight?: string;
    fontStyle?: string;
    fontVariant?: string;
    whiteSpace?: string;
}

measureSvgTextWidth

Cette fonction mesure la largeur du texte avec les propriétés de texte SVG spécifiques.

function measureSvgTextWidth(textProperties: TextProperties, text?: string): number;

Exemple d’utilisation de measureSvgTextWidth :

import { textMeasurementService } from "powerbi-visuals-utils-formattingutils";
import TextProperties = textMeasurementService.TextProperties;
// ...

let textProperties: TextProperties = {
    text: "Microsoft PowerBI",
    fontFamily: "sans-serif",
    fontSize: "24px"
};

textMeasurementService.measureSvgTextWidth(textProperties);

// returns: 194.71875

measureSvgTextRect

Cette fonction retourne un rectangle avec les propriétés de texte SVG données.

function measureSvgTextRect(textProperties: TextProperties, text?: string): SVGRect;

Exemple d’utilisation de measureSvgTextRect :

import { textMeasurementService } from "powerbi-visuals-utils-formattingutils";
import TextProperties = textMeasurementService.TextProperties;
// ...

let textProperties: TextProperties = {
    text: "Microsoft PowerBI",
    fontFamily: "sans-serif",
    fontSize: "24px"
};

textMeasurementService.measureSvgTextRect(textProperties);

// returns: { x: 0, y: -22, width: 194.71875, height: 27 }

measureSvgTextHeight

Cette fonction mesure la hauteur du texte avec les propriétés de texte SVG spécifiques.

function measureSvgTextHeight(textProperties: TextProperties, text?: string): number;

Exemple d’utilisation de measureSvgTextHeight :

import { textMeasurementService } from "powerbi-visuals-utils-formattingutils";
import TextProperties = textMeasurementService.TextProperties;
// ...


let textProperties: TextProperties = {
    text: "Microsoft PowerBI",
    fontFamily: "sans-serif",
    fontSize: "24px"
};

textMeasurementService.measureSvgTextHeight(textProperties);

// returns: 27

estimateSvgTextBaselineDelta

Cette fonction retourne une base de référence des propriétés de texte SVG spécifiques.

function estimateSvgTextBaselineDelta(textProperties: TextProperties): number;

Exemple :

import { textMeasurementService } from "powerbi-visuals-utils-formattingutils";
import TextProperties = textMeasurementService.TextProperties;
// ...

let textProperties: TextProperties = {
    text: "Microsoft PowerBI",
    fontFamily: "sans-serif",
    fontSize: "24px"
};

textMeasurementService.estimateSvgTextBaselineDelta(textProperties);

// returns: 5

estimateSvgTextHeight

Cette fonction estime la hauteur du texte avec les propriétés de texte SVG spécifiques.

function estimateSvgTextHeight(textProperties: TextProperties, tightFightForNumeric?: boolean): number;

Exemple d’utilisation de estimateSvgTextHeight :

import { textMeasurementService } from "powerbi-visuals-utils-formattingutils";
import TextProperties = textMeasurementService.TextProperties;
// ...

let textProperties: TextProperties = {
    text: "Microsoft PowerBI",
    fontFamily: "sans-serif",
    fontSize: "24px"
};

textMeasurementService.estimateSvgTextHeight(textProperties);

// returns: 27

Pour obtenir un exemple, consultez code visuel personnalisé.

measureSvgTextElementWidth

Cette fonction mesure la largeur du svgElement.

function measureSvgTextElementWidth(svgElement: SVGTextElement): number;

Exemple d’utilisation de measureSvgTextElementWidth :

import { textMeasurementService } from "powerbi-visuals-utils-formattingutils";
// ...

let svg: D3.Selection = d3.select("body").append("svg");

svg.append("text")
    .text("Microsoft PowerBI")
    .attr({
        "x": 25,
        "y": 25
    })
    .style({
        "font-family": "sans-serif",
        "font-size": "24px"
    });

let textElement: D3.Selection = svg.select("text");

textMeasurementService.measureSvgTextElementWidth(textElement.node());

// returns: 194.71875

getMeasurementProperties

Cette fonction extrait les propriétés de mesure du texte de l’élément DOM donné.

function getMeasurementProperties(element: Element): TextProperties;

Exemple d’utilisation de getMeasurementProperties :

import { textMeasurementService } from "powerbi-visuals-utils-formattingutils";
// ...

let element: JQuery = $(document.createElement("div"));

element.text("Microsoft PowerBI");

element.css({
    "width": 500,
    "height": 500,
    "font-family": "sans-serif",
    "font-size": "32em",
    "font-weight": "bold",
    "font-style": "italic",
    "white-space": "nowrap"
});

textMeasurementService.getMeasurementProperties(element.get(0));

/* returns: {
    fontFamily:"sans-serif",
    fontSize: "32em",
    fontStyle: "italic",
    fontVariant: "",
    fontWeight: "bold",
    text: "Microsoft PowerBI",
    whiteSpace: "nowrap"
}*/

getSvgMeasurementProperties

Cette fonction extrait les propriétés de mesure du texte de l’élément de texte SVG donné.

function getSvgMeasurementProperties(svgElement: SVGTextElement): TextProperties;

Exemple d’utilisation de getSvgMeasurementProperties :

import { textMeasurementService } from "powerbi-visuals-utils-formattingutils";
// ...

let svg: D3.Selection = d3.select("body").append("svg");

let textElement: D3.Selection = svg.append("text")
    .text("Microsoft PowerBI")
    .attr({
        "x": 25,
        "y": 25
    })
    .style({
        "font-family": "sans-serif",
        "font-size": "24px"
    });

textMeasurementService.getSvgMeasurementProperties(textElement.node());

/* returns: {
    "text": "Microsoft PowerBI",
    "fontFamily": "sans-serif",
    "fontSize": "24px",
    "fontWeight": "normal",
    "fontStyle": "normal",
    "fontVariant": "normal",
    "whiteSpace": "nowrap"
}*/

getDivElementWidth

Cette fonction retourne la largeur d’un élément div.

function getDivElementWidth(element: JQuery): string;

Exemple d’utilisation de getDivElementWidth :

import { textMeasurementService } from "powerbi-visuals-utils-formattingutils";
// ...

let svg: Element = d3.select("body")
    .append("div")
    .style({
        "width": "150px",
        "height": "150px"
    })
    .node();

textMeasurementService.getDivElementWidth(svg)

// returns: 150px

getTailoredTextOrDefault

Compare la taille de texte d’une étiquette à la taille disponible, et affiche des points de suspension quand la taille disponible est plus petite.

function getTailoredTextOrDefault(textProperties: TextProperties, maxWidth: number): string;

Exemple d’utilisation de getTailoredTextOrDefault :

import { textMeasurementService } from "powerbi-visuals-utils-formattingutils";
import TextProperties = textMeasurementService.TextProperties;
// ...

let textProperties: TextProperties = {
    text: "Microsoft PowerBI!",
    fontFamily: "sans-serif",
    fontSize: "24px"
};

textMeasurementService.getTailoredTextOrDefault(textProperties, 100);

// returns: Micros...

Extensions de chaîne

Le module fournit les fonctions suivantes :

endsWith

Cette fonction vérifie si une chaîne se termine par une sous-chaîne.

function endsWith(str: string, suffix: string): boolean;

Exemple d’utilisation de endsWith :

import { stringExtensions } from "powerbi-visuals-utils-formattingutils";
// ...

stringExtensions.endsWith("Power BI", "BI");

// returns: true

equalIgnoreCase

Cette fonction compare les chaînes en ignorant la casse.

function equalIgnoreCase(a: string, b: string): boolean;

Exemple d’utilisation de equalIgnoreCase :

import { stringExtensions } from "powerbi-visuals-utils-formattingutils";
// ...

stringExtensions.equalIgnoreCase("Power BI", "power bi");

// returns: true

startsWith

Cette fonction vérifie si une chaîne commence par une sous-chaîne.

function startsWith(a: string, b: string): boolean;

Exemple d’utilisation de startsWith :

import { stringExtensions } from "powerbi-visuals-utils-formattingutils";
// ...

stringExtensions.startsWith("Power BI", "Power");

// returns: true

contains

Cette fonction vérifie si une chaîne contient une sous-chaîne spécifiée.

function contains(source: string, substring: string): boolean;

Exemple d’utilisation de la méthode contains :

import { stringExtensions } from "powerbi-visuals-utils-formattingutils";
// ...

stringExtensions.contains("Microsoft Power BI Visuals", "Power BI");

// returns: true

isNullOrEmpty

Vérifie si une chaîne a la valeur Null, n’est pas définie ou est vide.

function isNullOrEmpty(value: string): boolean;

Exemple de méthode isNullOrEmpty :

import { stringExtensions } from "powerbi-visuals-utils-formattingutils";
// ...

stringExtensions.isNullOrEmpty(null);

// returns: true

Formateur de valeurs

Le module fournit les fonctions, interfaces et classes suivantes :

IValueFormatter

Cette interface décrit les méthodes et les propriétés publiques du formateur.

interface IValueFormatter {
    format(value: any): string;
    displayUnit?: DisplayUnit;
    options?: ValueFormatterOptions;
}

IValueFormatter.format

Cette méthode met en forme la valeur spécifique.

function format(value: any, format?: string, allowFormatBeautification?: boolean): string;

Exemples pour IValueFormatter.format :

Formats des milliers

import { valueFormatter } from "powerbi-visuals-utils-formattingutils";

let iValueFormatter = valueFormatter.create({ value: 1001 });

iValueFormatter.format(5678);

// returns: "5.68K"

Formats des millions

import { valueFormatter } from "powerbi-visuals-utils-formattingutils";

let iValueFormatter = valueFormatter.create({ value: 1e6 });

iValueFormatter.format(1234567890);

// returns: "1234.57M"

Formats des milliards

import { valueFormatter } from "powerbi-visuals-utils-formattingutils";

let iValueFormatter = valueFormatter.create({ value: 1e9 });

iValueFormatter.format(1234567891236);

// returns: 1234.57bn

Format des trillions

import { valueFormatter } from "powerbi-visuals-utils-formattingutils";

let iValueFormatter = valueFormatter.create({ value: 1e12 });

iValueFormatter.format(1234567891236);

// returns: 1.23T

Format d’exposant

import { valueFormatter } from "powerbi-visuals-utils-formattingutils";

let iValueFormatter = valueFormatter.create({ format: "E" });

iValueFormatter.format(1234567891236);

// returns: 1.234568E+012

Sélecteur de culture

import { valueFormatter } from "powerbi-visuals-utils-formattingutils";

let valueFormatterUK = valueFormatter.create({ cultureSelector: "en-GB" });

valueFormatterUK.format(new Date(2007, 2, 3, 17, 42, 42));

// returns: 02/03/2007 17:42:42

let valueFormatterUSA = valueFormatter.create({ cultureSelector: "en-US" });

valueFormatterUSA.format(new Date(2007, 2, 3, 17, 42, 42));

// returns: 2/3/2007 5:42:42 PM

Format de pourcentage

import { valueFormatter } from "powerbi-visuals-utils-formattingutils";

let iValueFormatter = valueFormatter.create({ format: "0.00 %;-0.00 %;0.00 %" });

iValueFormatter.format(0.54);

// returns: 54.00 %

Format des dates

import { valueFormatter } from "powerbi-visuals-utils-formattingutils";

let date = new Date(2016, 10, 28, 15, 36, 0),
    iValueFormatter = valueFormatter.create({});

iValueFormatter.format(date);

// returns: 10/28/2016 3:36:00 PM

Format booléen

import { valueFormatter } from "powerbi-visuals-utils-formattingutils";

let iValueFormatter = valueFormatter.create({});

iValueFormatter.format(true);

// returns: True

Précision personnalisée

import { valueFormatter } from "powerbi-visuals-utils-formattingutils";

let iValueFormatter = valueFormatter.create({ value: 0, precision: 3 });

iValueFormatter.format(3.141592653589793);

// returns: 3.142

Pour obtenir un exemple, consultez code visuel personnalisé.

ValueFormatterOptions

Cette interface décrit les options d’IValueFormatter et les options de la fonction create.

import { valueFormatter } from "powerbi-visuals-utils-formattingutils";
import ValueFormatterOptions = valueFormatter.ValueFormatterOptions;

interface ValueFormatterOptions {
    /** The format string to use. */
    format?: string;
    /** The data value. */
    value?: any;
    /** The data value. */
    value2?: any;
    /** The number of ticks. */
    tickCount?: any;
    /** The display unit system to use */
    displayUnitSystemType?: DisplayUnitSystemType;
    /** True if we are formatting single values in isolation (e.g. card), as opposed to multiple values with a common base (e.g. chart axes) */
    formatSingleValues?: boolean;
    /** True if we want to trim off unnecessary zeroes after the decimal and remove a space before the % symbol */
    allowFormatBeautification?: boolean;
    /** Specifies the maximum number of decimal places to show*/
    precision?: number;
    /** Detect axis precision based on value */
    detectAxisPrecision?: boolean;
    /** Specifies the column type of the data value */
    columnType?: ValueTypeDescriptor;
    /** Specifies the culture */
    cultureSelector?: string;
}

create

Cette méthode crée une instance d’IValueFormatter.

import { valueFormatter } from "powerbi-visuals-utils-formattingutils";
import create = valueFormatter.create;

function create(options: ValueFormatterOptions): IValueFormatter;

Exemple d’utilisation de create

import { valueFormatter } from "powerbi-visuals-utils-formattingutils";

valueFormatter.create({});

// returns: an instance of IValueFormatter.

format

Alternative pour mettre en forme la valeur sans créer IValueFormatter. Utile pour les cas avec une chaîne de formats dynamiques

import { format } from "powerbi-visuals-utils-formattingutils";
import format = valueFormatter.format;

function format(value: any, format?: string, allowFormatBeautification?: boolean, cultureSelector?: string): string;

Exemple d’utilisation du format

import { valueFormatter } from "powerbi-visuals-utils-formattingutils";

const value = 12
const format = '¥ #,0'
valueFormatter.format(value, format);

// returns: formatted value as string (¥ 12)

Contenu connexe

Ajouter la langue locale à votre visuel Power BI