Number.prototype.toLocaleString()

toLocaleString() 方法返回这个数字在特定语言环境下的表示字符串。

新的 localesoptions 参数让应用程序可以指定要进行格式转换的语言,并且定制函数的行为。在旧的实现中,会忽略 localesoptions 参数,使用的语言环境和返回的字符串的形式完全取决于实现方式。

语法

numObj.toLocaleString([locales [, options]])

参数

查阅浏览器兼容性部分,了解哪些浏览器支持 localesoptions 参数,通过示例: 检查 localesoptions 参数的支持了解特征检测。

注意: ECMAScript 国际化 API,在 Firefox 29 中得以实施,增加了 locales 参数的 Number.toLocaleString 方法。如果参数为 undefined,此方法返回本地操作系统指定的位数,而 Firefox 的早期版本中返回阿拉伯语数字。这一变化已被报告为向后影响的兼容性问题并可能会被尽快修复。(bug 999003)

locales

可选。缩写语言代码(BCP 47 language tag,例如: cmn-Hans-CN)的字符串或者这些字符串组成的数组. 关于参数 locales 的一般形式和解释请参见Intl page. 下面的这些 Unicode 扩展键也是被允许的:

译者注:下面扩展的使用方式是language[-scripts][-region]-u-nu-*,例如:zh-u-nu-hanidec(表示中文十进制数字) 

nu
要使用的编号系统。可能的值有: "arab", "arabext", "bali", "beng", "deva", "fullwide", "gujr", "guru", "hanidec"(中文十进制数字), "khmr", "knda", "laoo", "latn", "limb", "mlym", "mong", "mymr", "orya", "tamldec", "telu", "thai", "tibt".
options

可选. 包含一些或所有的下面属性的类:

  • “decimal” 用于纯数字格式;
  • “currency” 用于货币格式;
  • “percent” 用于百分比格式;
  • “unit”   用于单位格式
localeMatcher
使用的 local 的匹配算法. 可能的值有 "lookup 和 "best fit"; 默认值是 "best fit". 有关此选项更多的信息, 请参见 Intl page.
style
要使用的格式样式,默认为 “decimal”。
numberingSystem 
编号系统。可能的值包括:"arab","arabext"," bali","beng","deva","fullwide"," gujr","guru","hanidec","khmr"," knda","laoo", "latn","limb","mlym"," mong","mymr","orya","tamldec"," telu","thai","tibt"。
unit
unit 格式中使用的单位,可能的值为在 UTS #35, Part 2, Section 6 定义的核心单元标识符。已从完整列表中选择了一个单位子集以用于ECMAScript。可以将成对的简单单位与 “ -per-” 连接以组成一个复合单位。没有默认值;如果 style“unit”,必须提供unit 属性。
unitDisplay
unit 格式化中使用的单位格式化样式,默认值为“ short”。
  • “long” (e.g., 16 litres)
  • “short“ (e.g., 16 l)
  • ”narrow“ (e.g., 16l)
currency
在货币格式化中使用的货币符号. 可能的值是ISO的货币代码 (the ISO 4217 currency codes,) 例如 "USD" 表示美元, "EUR" 表示欧元, 或者 "CNY"是人民币 — 更多请参考 Current currency & funds code list。没有默认值,如果 style“currency”,必须提 currency 属性.
currencyDisplay
如何在货币格式化中显示货币. 可能的值有 "symbol" 表示使用本地化的货币符号,例如 €, "code" 表示使用国际标准组织货币代码, "name" 表示使用本地化的货币名称,如 "dollar"; 默认值是 "symbol".
useGrouping
是否使用分组分隔符,如千位分隔符或千/万/亿分隔符。可能的值是 true 和 false,默认值是 true。

下面的属性分为两组:minimumintegerdigitsminimumfractiondigitsmaximumfractiondigits 作为一组,minimumsignificantdigitsmaximumsignificantdigits 作为一组。如果定义了第二组中的任意一个属性,则忽略第一组的设置.

minimumIntegerDigits
使用的整数数字的最小数目.可能的值是从1到21,默认值是1.
minimumFractionDigits
使用的小数位数的最小数目.可能的值是从 0 到 20;默认为普通的数字和百分比格式为 0;默认为货币格式是由 ISO 4217 currency code list  提供 (如果列表中没有提供则值为 2)。
maximumFractionDigits
使用的小数位数的最大数目。可能的值是从 0 到 20;纯数字格式的默认值是minimumfractiondigits 和 3 中大的那一个;货币格式默认值是minimumfractiondigitsISO 4217 currency code list 中大的那一个(如果列表中没有提供则值为2);百分比格式默认值是 minimumfractiondigits 和 0 中大的那一个。
minimumSignificantDigits
使用的有效数字的最小数目。可能的值是从1到21;默认值是1。
maximumSignificantDigits
使用的有效数字的最大数量。可能的值是从1到21;默认是 21.
notation
该号码应显示的格式,默认为 “standard”
  • "standard"  纯数字格式;
  • "scientific"  返回格式化数字的大小顺序;
  • "engineering"  当被三除时返回十的指数
  • "compact" 代表指数的字符串,默认使用 “short” 格式
    • "compactDisplay" 仅在 notation“compact” 时使用,采用 “short”(默认)或“long

返回值

返回一个语言环境下的表示字符串。

示例

使用 toLocaleString

在没有指定区域的基本使用时,返回使用默认的语言环境和默认选项格式化的字符串。

var number = 3500;

console.log(number.toLocaleString()); // Displays "3,500" if in U.S. English locale

检查 locales 和 options 参数的支持

localesoptions 参数目前还不是所有浏览器都支持的。在 ES5.1 和更新的实现中检查支持情况,可以依靠使用非法参数时规定抛出的 RangeError 异常:

function toLocaleStringSupportsLocales() {
  var number = 0;
  try {
    number.toLocaleString('i');
  } catch (e) {
    return e​.name === 'RangeError';
  }
  return false;
}

早于 ES5.1 的实现中,如果带参数调用 toLocaleString 并不会抛出范围异常。

在所有宿主环境下,包括那些支持比 ed 5.1 还早的 ECMA-262 的环境,都能有效检测的方法是直接检测 ECMA-402 中的其它特性,它指定 Number.prototype.toLocaleString 需要支持地区选项:

function toLocaleStringSupportsOptions() {
  return !!(typeof Intl == 'object' && Intl && typeof Intl.NumberFormat == 'function');
}

它测试全局的 Intl 对象,检测它不是 null 并且有 NumberFormat 的方法。

使用 locales

这个示例展示了不同地区数字格式的差异。为了设置你的应用程序界面下使用的语言格式,请确保使用 locales 参数指定了使用的语言(可能还有一些备用语言):

var number = 123456.789;

// 德国使用逗号作为小数分隔符,分位周期为千位
console.log(number.toLocaleString('de-DE'));
// → 123.456,789

// 在大多数阿拉伯语国家使用阿拉伯语数字
console.log(number.toLocaleString('ar-EG'));
// → ١٢٣٤٥٦٫٧٨٩

// 印度使用千位/拉克(十万)/克若尔(千万)分隔
console.log(number.toLocaleString('en-IN'));
// → 1,23,456.789

// nu 扩展字段要求编号系统,e.g. 中文十进制
console.log(number.toLocaleString('zh-Hans-CN-u-nu-hanidec'));
// → 一二三,四五六.七八九

// 当请求不支持的语言时,例如巴厘语,加入一个备用语言,比如印尼语
console.log(number.toLocaleString(['ban', 'id']));
// → 123.456,789

使用 options

通过 toLocaleString 返回的结果可以通过 options 参数进行定制:

var number = 123456.789;

// 要求货币格式
console.log(number.toLocaleString('de-DE', { style: 'currency', currency: 'EUR' }));
// → 123.456,79 €

// 日元不使用小数位
console.log(number.toLocaleString('ja-JP', { style: 'currency', currency: 'JPY' }))
// → ¥123,457

// 限制三位有效数字
console.log(number.toLocaleString('en-IN', { maximumSignificantDigits: 3 }));
// → 1,23,000

性能

当格式化大量数字时,最好建立一个 NumberFormat 对象并且使用它提供的 NumberFormat.format 方法。

规范

规范 状态 注解
ECMAScript 3rd Edition. Implemented in JavaScript 1.5 Standard Initial definition.
ECMAScript 5.1 (ECMA-262)
Number.prototype.toLocaleString
Standard  
ECMAScript 2015 (6th Edition, ECMA-262)
Number.prototype.toLocaleString
Standard  
ECMAScript Internationalization API Specification, 1st Edition (ECMA-402) Standard  

浏览器兼容性

BCD tables only load in the browser

 

相关链接