Formatierungshilfsprogramme

Artikel
10/10/2024

Formatierungshilfsprogramme enthalten die Klassen, Schnittstellen und Methoden zur Formatierung von Werten. Sie enthalten auch Erweiterungsmethoden zur Verarbeitung von Zeichenfolgen und zur Messung der Textgröße in SVG- bzw. HTML-Dokumenten.

Textmessungsdienst

Das Modul stellt die folgenden Funktionen und Schnittstellen zur Verfügung:

TextProperties-Schnittstelle

Die Schnittstelle beschreibt die allgemeinen Eigenschaften des Texts.

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

measureSvgTextWidth

Die Funktion misst die Breite des Texts mit den angegebenen SVG-Texteigenschaften.

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

Beispiel für die Verwendung von 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

Diese Funktion gibt ein rect-Element mit den angegebenen SVG-Texteigenschaften zurück.

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

Beispiel für die Verwendung von 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

Die Funktion misst die Höhe des Texts mit den angegebenen SVG-Texteigenschaften.

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

Beispiel für die Verwendung von 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

Diese Funktion gibt eine Baseline mit den angegebenen SVG-Texteigenschaften zurück.

function estimateSvgTextBaselineDelta(textProperties: TextProperties): number;

Beispiel:

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

Die Funktion schätzt die Höhe des Texts mit den angegebenen SVG-Texteigenschaften.

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

Beispiel für die Verwendung von 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

Ein Beispiel finden Sie unter benutzerdefinierter visueller Code.

measureSvgTextElementWidth

Die Funktion misst die Breite von „svgElement“.

function measureSvgTextElementWidth(svgElement: SVGTextElement): number;

Beispiel für die Verwendung von „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

Diese Funktion ruft die Eigenschaften der Textmessung des angegebenen DOM-Elements ab.

function getMeasurementProperties(element: Element): TextProperties;

Beispiel für die Verwendung von 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

Diese Funktion ruft die Eigenschaften der Textmessung des angegebenen SVG-Textelements ab.

function getSvgMeasurementProperties(svgElement: SVGTextElement): TextProperties;

Beispiel für die Verwendung von 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

Die Funktion gibt die Breite eines div-Elements zurück.

function getDivElementWidth(element: JQuery): string;

Beispiel für die Verwendung von 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

Diese Funktion vergleicht die Textgröße von Bezeichnungen mit der verfügbaren Größe und rendert Ellipsen, wenn die verfügbare Größe kleiner ist.

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

Beispiel für die Verwendung von 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...

Zeichenfolgenerweiterungen

Das Modul stellt die folgenden Funktionen zur Verfügung:

endsWith

Die Funktion überprüft, ob eine Zeichenfolge mit einer Teilzeichenfolge endet.

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

Beispiel für die Verwendung von endsWith:

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

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

// returns: true

equalIgnoreCase

Diese Funktion vergleicht Zeichenfolgen, wobei Groß-/Kleinbuchstaben ignoriert werden.

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

Beispiel für die Verwendung von equalIgnoreCase:

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

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

// returns: true

startsWith

Die Funktion überprüft, ob eine Zeichenfolge mit einer Teilzeichenfolge beginnt.

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

Beispiel für die Verwendung von startsWith:

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

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

// returns: true

contains

Diese Funktion überprüft, ob eine Zeichenfolge eine angegebene Teilzeichenfolge enthält.

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

Beispiel für die Verwendung der contains-Methode:

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

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

// returns: true

isNullOrEmpty

Diese Funktion überprüft, ob eine Zeichenfolge NULL, nicht definiert oder leer ist.

function isNullOrEmpty(value: string): boolean;

Beispiel für die isNullOrEmpty-Methode:

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

stringExtensions.isNullOrEmpty(null);

// returns: true

Wertformatierung

Das Modul stellt die folgenden Funktionen, Schnittstellen und Klassen zur Verfügung:

IValueFormatter

Diese Schnittstelle beschreibt öffentliche Methoden und Eigenschaften des Formatierers.

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

IValueFormatter.format

Diese Methode formatiert den angegebenen Wert.

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

Beispiele für IValueFormatter.format:

Tausenderformate

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

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

iValueFormatter.format(5678);

// returns: "5.68K"

Millionenformate

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

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

iValueFormatter.format(1234567890);

// returns: "1234.57M"

Milliardenformate

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

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

iValueFormatter.format(1234567891236);

// returns: 1234.57bn

Trillionenformat

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

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

iValueFormatter.format(1234567891236);

// returns: 1.23T

Exponentenformat

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

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

iValueFormatter.format(1234567891236);

// returns: 1.234568E+012

Kulturauswahl

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

Prozentformat

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 %

Datumsformat

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

Boolesches Format

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

let iValueFormatter = valueFormatter.create({});

iValueFormatter.format(true);

// returns: True

Angepasste Genauigkeit

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

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

iValueFormatter.format(3.141592653589793);

// returns: 3.142

Ein Beispiel finden Sie unter benutzerdefinierter visueller Code.

ValueFormatterOptions

Diese Schnittstelle beschreibt options der IValueFormatter-Schnittstelle und der Optionen der create-Funktion.

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

Diese Methode erstellt eine Instanz von IValueFormatter.

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

function create(options: ValueFormatterOptions): IValueFormatter;

Beispiel für die Verwendung von „create“

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

valueFormatter.create({});

// returns: an instance of IValueFormatter.

format

Alternative Möglichkeit zum Formatieren des Werts ohne Erstellen von IValueFormatter. Nützlich für Fälle mit dynamischer Formatzeichenfolge

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

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

Beispiel für die Verwendung eines Formats

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

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

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

Fügen Sie die lokale Power BI-Sprache zum Power BI-Visual hinzu

Freigeben über

Formatierungshilfsprogramme

Textmessungsdienst

TextProperties-Schnittstelle

measureSvgTextWidth

measureSvgTextRect

measureSvgTextHeight

estimateSvgTextBaselineDelta

estimateSvgTextHeight

measureSvgTextElementWidth

getMeasurementProperties

getSvgMeasurementProperties

getDivElementWidth

getTailoredTextOrDefault

Zeichenfolgenerweiterungen

endsWith

equalIgnoreCase

startsWith

contains

isNullOrEmpty

Wertformatierung

IValueFormatter

IValueFormatter.format

Tausenderformate

Millionenformate

Milliardenformate

Trillionenformat

Exponentenformat

Kulturauswahl

Prozentformat

Datumsformat

Boolesches Format

Angepasste Genauigkeit

ValueFormatterOptions

create

Beispiel für die Verwendung von „create“

format

Beispiel für die Verwendung eines Formats

Feedback

Zusätzliche Ressourcen

Freigeben über

Formatierungshilfsprogramme

Textmessungsdienst

TextProperties-Schnittstelle

measureSvgTextWidth

measureSvgTextRect

measureSvgTextHeight

estimateSvgTextBaselineDelta

estimateSvgTextHeight

measureSvgTextElementWidth

getMeasurementProperties

getSvgMeasurementProperties

getDivElementWidth

getTailoredTextOrDefault

Zeichenfolgenerweiterungen

endsWith

equalIgnoreCase

startsWith

contains

isNullOrEmpty

Wertformatierung

IValueFormatter

IValueFormatter.format

Tausenderformate

Millionenformate

Milliardenformate

Trillionenformat

Exponentenformat

Kulturauswahl

Prozentformat

Datumsformat

Boolesches Format

Angepasste Genauigkeit

ValueFormatterOptions

create

Beispiel für die Verwendung von „create“

format

Beispiel für die Verwendung eines Formats

Zugehöriger Inhalt

Feedback

Zusätzliche Ressourcen