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.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读。
不指定地区时用哪个地区
用系统的首选语言,也就是「设置 → 通用 → 语言与地区」里排在第一位的那个语言,连同它的地区。
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() 返回的是一份新的对象,改它不影响格式化。
示例
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 |
参见
- 按地区显示数字和金额:金额、固定小数位、涨跌幅、大数、很大的整数
Intl.DateTimeFormat:日期和时间的格式化- 运行时怎么工作:有哪些标准的全局对象,哪些没有