Skip to content

Intl.NumberFormat ​

Intl.NumberFormat 表示一个按某个地区的习惯把数字写成文字的格式化对象,可以写普通的数、金额、百分比。同一个数 1234567.891,美国写成 1,234,567.891,德国写成 1.234.567,891,印度写成 12,34,567.891。

Intl 是 ECMAScript 的国际化接口。这里有两个类:

  • Intl.NumberFormat:数字、金额、百分比。Number.prototype.toLocaleString() 和 BigInt.prototype.toLocaleString() 用的是它。这一页讲它。
  • Intl.DateTimeFormat:日期和时间。Date 的三个 toLocale*String() 用的是它。

写法和浏览器里完全相同,按标准(ECMA-402)实现。已经会用浏览器里的 Intl.NumberFormat 的话,直接照原样写。

怎么显示金额、百分比、涨跌幅、大数,见指南按地区显示数字和金额。

继承关系:Intl.NumberFormat

构造函数 ​

Intl.NumberFormat()

按给的地区和选项建一个格式化对象。建好之后不能改。

静态方法 ​

方法说明
Intl.NumberFormat.supportedLocalesOf()从给的地区里挑出系统有数据的

实例方法 ​

方法说明
format()把一个值写成文字。已经绑定在这个对象上,可以单独取出来用
resolvedOptions()实际用的地区和选项,默认值已经填上
formatToParts()调用时抛 TypeError
formatRange()调用时抛 TypeError
formatRangeToParts()调用时抛 TypeError

相关的函数 ​

下面这几个不是 Intl.NumberFormat 的成员,但用的是同一套地区数据,放在这里一起说明。

函数说明
Intl.getCanonicalLocales()把地区标签改成规范的大小写
Number.prototype.toLocaleString()按地区把一个数写成文字。BigInt 的同名方法相同
String.prototype.normalize()把字符串换成 Unicode 的规范形式

结果和浏览器一致吗 ​

指定了地区时,和同一台设备上的 Safari 逐条相同。 地区的数据(分隔符用什么、货币符号怎么写)来自 iOS 系统,Safari 用的也是这一份。

不指定地区时可能和 Safari 不同:用哪个地区,两边的取法不一样,见不指定地区时用哪个地区。

和 Chrome 不保证每个字符都相同。Chrome 自带另一份地区数据,比如瑞士德语的千分位,Safari 用 ',Chrome 用 ’。选项怎么解析、默认值是什么、什么情况报错,三者相同。

所以不要把格式化的结果当作固定的字符串去比较或解析。要比较数值,比较数本身。

地区标签 ​

地区用一个字符串表示,叫地区标签,比如 'en-US'、'zh-CN'、'de-CH'。前一段是语言,后一段是国家或地区。

  • 大小写不敏感,'EN-us' 和 'en-US' 一样。
  • 用连字符,不用下划线。'en_US' 抛 RangeError。
  • 系统没有这个地区的数据时,从后往前一段一段去掉再找。'en-ZZ' 按 'en' 处理。整个语言都没有时('xx')用系统的首选语言,不报错。
  • 可以给一个数组,用第一个系统有的:new Intl.NumberFormat(['xx', 'de-DE']) 用的是 de-DE。
  • 实际用了哪个地区,从 resolvedOptions() 的 locale 读。

不指定地区时用哪个地区 ​

用系统的首选语言,也就是「设置 → 通用 → 语言与地区」里排在第一位的那个语言,连同它的地区。

js
console.log(new Intl.NumberFormat().resolvedOptions().locale);

结果:系统语言是简体中文、地区是中国大陆时,控制台输出 zh-CN;简体中文、地区是香港时输出 zh-Hans-HK;德语、地区是奥地利时输出 de-AT。

注意:这一条和 Safari 不同。Safari 里的网页拿到的不是系统语言本身:浏览器会先把它换成少数几种常见的语言,让网站没法靠语言设置认出用户。所以同一台手机上,网页里不指定地区的结果可能和这里不同:

系统的首选语言这里Safari 里的网页
简体中文(香港)zh-Hans-HKzh-CN
德语(奥地利)de-ATde-DE
法语(瑞士)fr-CHfr-FR
英语(爱尔兰)en-IEen-GB
日语(日本)ja-JPja

这里按用户实际选的地区来。比如德语奥地利的金额写法和德语德国不同,用户选了奥地利,就按奥地利的写。语言和地区一致时(简体中文加中国大陆、英语加美国)两边相同。

不支持的选项 ​

用到不支持的选项时,构造 Intl.NumberFormat 会抛 RangeError,错误信息里写明是哪个选项:

RangeError: notation: "engineering" is not supported by this runtime

不支持的选项列在构造函数的页面上。它们不会被悄悄忽略。

TypeScript 自带的类型认为这些选项都合法,所以类型检查查不出来,只有运行时会抛。

选项只在构造时读一次 ​

Intl.NumberFormat 建好之后不能改。要换一种写法,再建一个。resolvedOptions() 返回的是一份新的对象,改它不影响格式化。

示例 ​

js
const price = 1234.5;

// 1. 按系统的地区写数字
console.log(price.toLocaleString());

// 2. 写成货币。地区决定写法,currency 决定是哪种货币
const usd = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' });
console.log(usd.format(price));

// 3. 同一个格式化对象可以反复用
console.log([19.99, 5, 1200].map(usd.format).join(' / '));

// 4. 写成百分比
const percent = new Intl.NumberFormat('en-US', { style: 'percent', maximumFractionDigits: 1 });
console.log(percent.format(0.256));

// 5. 大数写成紧凑的形式
console.log(new Intl.NumberFormat('zh-CN', { notation: 'compact' }).format(1234567.891));

结果:系统语言是简体中文时,控制台依次输出:

1,234.5
$1,234.50
$19.99 / $5.00 / $1,200.00
25.6%
123万

这段代码没有作为一个整体在模拟器运行过。其中每一种调用都在验收用例里和网页比对过。

和 Web 的差别 ​

情况浏览器这里
不指定地区时用哪个地区Safari 把系统语言换成少数几种常见的语言用系统的首选语言本身,见不指定地区时用哪个地区
结果的每个字符各浏览器有自己的地区数据指定地区时和同一台设备上的 Safari 逐条相同
一部分选项支持构造时抛 RangeError,见不支持的选项
formatToParts()、formatRange()、formatRangeToParts()有调用时抛 TypeError
BigInt 和十进制字符串的有效数字不限最多 38 位,再长抛 RangeError

参见 ​