GT ClassMethodsFormatting
formatNum
formatNum 方法的 API 参考，用于按 locale 约定格式化数字
概述
formatNum 方法使用 Internationalization API 按照特定 locale 的惯例格式化数字。
它会根据目标 locale 自动处理小数点、千位分隔符以及数字系统。
const gt = new GT({ targetLocale: 'de' });
const formatted = gt.formatNum(1234.56, {
style: 'decimal',
minimumFractionDigits: 2
});
// 返回："1.234,56”（德语数字格式）参考资料
参数
| 名称 | 类型 | 说明 |
|---|---|---|
number | number | 要格式化的数值 |
options? | NumberFormatOptions | 可选的格式化选项 |
NumberFormatOptions
在 Intl.NumberFormatOptions 基础上扩展，增加对 locale 的额外指定：
| 名称 | 类型 | 描述 |
|---|---|---|
locales? | string | string[] | 覆盖用于格式化的 locale（默认使用实例的 locale） |
style? | 'decimal' | 'currency' | 'percent' | 'unit' | 数字格式化样式 |
currency? | string | 货币代码（当 style 为 'currency' 时必填） |
currencyDisplay? | 'symbol' | 'narrowSymbol' | 'code' | 'name' | 货币的展示方式 |
currencySign? | 'standard' | 'accounting' | 货币符号规则 |
unit? | string | 单位标识（当 style 为 'unit' 时必填） |
unitDisplay? | 'short' | 'narrow' | 'long' | 单位的展示方式 |
minimumIntegerDigits? | number | 最小整数位数（1–21） |
minimumFractionDigits? | number | 最小小数位数（0–20） |
maximumFractionDigits? | number | 最大小数位数（0–20） |
minimumSignificantDigits? | number | 最少有效位数（1–21） |
maximumSignificantDigits? | number | 最多有效位数（1–21） |
useGrouping? | boolean | 'always' | 'auto' | 'min2' | 是否使用分组分隔符 |
notation? | 'standard' | 'scientific' | 'engineering' | 'compact' | 数字记数法 |
compactDisplay? | 'short' | 'long' | 紧凑记数法的展示样式 |
signDisplay? | 'auto' | 'never' | 'always' | 'exceptZero' | 何时显示正负号 |
roundingMode? | 'ceil' | 'floor' | 'expand' | 'trunc' | 'halfCeil' | 'halfFloor' | 'halfExpand' | 'halfTrunc' | 'halfEven' | 舍入模式 |
roundingIncrement? | 1 | 2 | 5 | 10 | 20 | 25 | 50 | 100 | 舍入增量 |
trailingZeroDisplay? | 'auto' | 'stripIfInteger' | 是否显示末尾零 |
返回值
string - 按 locale 约定格式化的数字。
示例
基本数字格式化
import { GT } from 'generaltranslation';
const gt = new GT({ targetLocale: 'en-US' });
// 基本小数格式化
console.log(gt.formatNum(1234.567));
// 输出：“1,234.567”
// 德语 locale 格式化
console.log(gt.formatNum(1234.567, { locales: 'de-DE' }));
// Output: "1.234,567"
// 法语 locale 格式化
console.log(gt.formatNum(1234.567, { locales: 'fr-FR' }));
// Output: "1 234,567"货币格式
// 美元格式
console.log(gt.formatNum(1234.56, {
style: 'currency',
currency: 'USD'
}));
// 输出：“$1,234.56”
// 使用德语地区（de-DE）的欧元格式
console.log(gt.formatNum(1234.56, {
style: 'currency',
currency: 'EUR',
locales: 'de-DE'
}));
// 输出：“1.234,56 €”
// 货币显示选项
console.log(gt.formatNum(1234.56, {
style: 'currency',
currency: 'USD',
currencyDisplay: 'code'
}));
// 输出：“USD 1,234.56”
// 会计格式（负数用括号表示）
console.log(gt.formatNum(-1234.56, {
style: 'currency',
currency: 'USD',
currencySign: 'accounting'
}));
// 输出：“($1,234.56)”百分数与科学记数法
// 基本百分比
console.log(gt.formatNum(0.1234, { style: 'percent' }));
// 输出：“12%”
// 带小数位的百分比
console.log(gt.formatNum(0.1234, {
style: 'percent',
minimumFractionDigits: 1,
maximumFractionDigits: 2
}));
// 输出：“12.34%”
// 紧凑表示法
console.log(gt.formatNum(1234567, { notation: 'compact' }));
// 输出：“1.2M”
// 科学计数法
console.log(gt.formatNum(1234567, { notation: 'scientific' }));
// 输出：“1.235E6”注意事项
- 数字格式会自动遵循对应
locale的本地化约定 - 该方法使用浏览器原生的
Intl.NumberFormat，以获得最佳性能与准确性 - 货币格式需同时设置
style: 'currency'并提供有效的currency代码 - 单位格式需同时设置
style: 'unit'并提供有效的unit标识符
后续步骤
- 查阅
Intl.NumberFormat文档 以了解更多 options - 查看
format-currency以进行专门的 Currency 格式化 - 查看
format-message以进行包含数字插值的消息格式化 - 查看独立的
format-num，可在不依赖 GT 实例的情况下使用 - 查看
get-locale-properties以获取特定 locale 的格式化信息
本指南如何?