格式化公用程式

發行項
10/10/2024

格式化公用程式包含用於格式化值的類別、介面與方法。其也包含用於處理字串，以及測量 SVG/HTML 文件中文字大小的延伸器方法。

文字測量服務

此課程模組提供下列函式與介面：

TextProperties 介面

此介面描述文字的一般屬性。

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

measureSvgTextWidth

此函式會使用特定的 SVG 文字屬性來測量文字的寬度。

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

使用 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

此函式會使用指定的 SVG 文字屬性傳回一個矩形。

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

使用 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

此函式會使用特定的 SVG 文字屬性來測量文字的高度。

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

使用 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

此函式會傳回特定 SVG 文字屬性的基準線。

function estimateSvgTextBaselineDelta(textProperties: TextProperties): number;

範例：

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

此函式會使用特定的 SVG 文字屬性來預估文字的高度。

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

使用 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

如需範例，請參閱自訂視覺效果程式碼。

measureSvgTextElementWidth

此函式會測量 svgElement 的寬度。

function measureSvgTextElementWidth(svgElement: SVGTextElement): number;

使用 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

此函式會擷取指定 DOM 元素的文字測量屬性。

function getMeasurementProperties(element: Element): TextProperties;

使用 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

此函式會擷取指定 SVG 文字元素的文字測量屬性。

function getSvgMeasurementProperties(svgElement: SVGTextElement): TextProperties;

使用 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

此函式會傳回 div 元素的寬度。

function getDivElementWidth(element: JQuery): string;

使用 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

比較標籤的文字大小與可用大小，並在可用的大小較小時呈現省略符號。

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

使用 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...

字串延伸模組

此課程模組提供下列函式：

endsWith

此函式會檢查字串是否以子字串結尾。

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

使用 endsWith 的範例：

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

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

// returns: true

equalIgnoreCase

此函式會比較字串，並忽略大小寫。

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

使用 equalIgnoreCase 的範例：

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

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

// returns: true

startsWith

此函式會檢查字串是否以 substring 開始。

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

使用 startsWith 的範例：

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

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

// returns: true

contains

此函式會檢查字串是否包含指定子字串。

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

使用 contains 方法的範例：

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

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

// returns: true

isNullOrEmpty

檢查字串是否為 Null、或未定義，或空白。

function isNullOrEmpty(value: string): boolean;

isNullOrEmpty 方法的範例：

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

stringExtensions.isNullOrEmpty(null);

// returns: true

值格式器

此課程模組提供下列函式、介面與類別：

IValueFormatter

此介面描述格式器的公用方法和屬性。

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

IValueFormatter.format

此方法會格式化指定的值。

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

IValueFormatter.format 的範例：

千位格式

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

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

iValueFormatter.format(5678);

// returns: "5.68K"

百萬位格式

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

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

iValueFormatter.format(1234567890);

// returns: "1234.57M"

十億位格式

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

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

iValueFormatter.format(1234567891236);

// returns: 1234.57bn

兆位格式

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

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

iValueFormatter.format(1234567891236);

// returns: 1.23T

指數格式

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

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

iValueFormatter.format(1234567891236);

// returns: 1.234568E+012

文化特性選取器

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

百分比格式

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 %

日期格式

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

布林格式

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

let iValueFormatter = valueFormatter.create({});

iValueFormatter.format(true);

// returns: True

自訂精確度

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

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

iValueFormatter.format(3.141592653589793);

// returns: 3.142

如需範例，請參閱自訂視覺效果程式碼。

ValueFormatterOptions

此介面會描述 IValueFormatter 的 options 和 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

此方法會建立 IValueFormatter 的執行個體。

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

function create(options: ValueFormatterOptions): IValueFormatter;

使用 create 的範例

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

valueFormatter.create({});

// returns: an instance of IValueFormatter.

format

在不建立 IValueFormatter 的情況下格式化值的替代方法。對於動態格式字串的案例很實用

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

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

使用格式的範例

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

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

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

將本機語言新增至 Power BI 視覺效果

共用方式為

格式化公用程式

文字測量服務

TextProperties 介面

measureSvgTextWidth

measureSvgTextRect

measureSvgTextHeight

estimateSvgTextBaselineDelta

estimateSvgTextHeight

measureSvgTextElementWidth

getMeasurementProperties

getSvgMeasurementProperties

getDivElementWidth

getTailoredTextOrDefault

字串延伸模組

endsWith

equalIgnoreCase

startsWith

contains

isNullOrEmpty

值格式器

IValueFormatter

IValueFormatter.format

千位格式

百萬位格式

十億位格式

兆位格式

指數格式

文化特性選取器

百分比格式

日期格式

布林格式

自訂精確度

ValueFormatterOptions

create

使用 create 的範例

format

使用格式的範例

意見反應

其他資源

共用方式為

格式化公用程式

文字測量服務

TextProperties 介面

measureSvgTextWidth

measureSvgTextRect

measureSvgTextHeight

estimateSvgTextBaselineDelta

estimateSvgTextHeight

measureSvgTextElementWidth

getMeasurementProperties

getSvgMeasurementProperties

getDivElementWidth

getTailoredTextOrDefault

字串延伸模組

endsWith

equalIgnoreCase

startsWith

contains

isNullOrEmpty

值格式器

IValueFormatter

IValueFormatter.format

千位格式

百萬位格式

十億位格式

兆位格式

指數格式

文化特性選取器

百分比格式

日期格式

布林格式

自訂精確度

ValueFormatterOptions

create

使用 create 的範例

format

使用格式的範例

相關內容

意見反應

其他資源