Number.prototype.toLocaleString()

概述

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

新  locales 和  options 论据让应用程序指定的格式约定,应使用和自定义函数的行为语言。在旧的实现,这忽略localesoptions参数,使用的语言环境和返回的字符串的形式完全取决于实现方式。

语法

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

参数

检查 Browser compatibility 部分部分,看看哪些浏览器都支持locales和options参数,并举例 Example: Checking for support for locales and options arguments 特征检测。

ECMAScript的国际化API,与Firefox 29实施,增加了locales参数的 Number.toLocaleString 方法。如果参数为undefined,此方法返回本地化的操作系统指定的位数,而Firefox的早期版本中返回的英文数字。这一变化已被报告为影响向后兼容性可能尽快修复回归。 (bug 999003)

locales

Optional. A string with a BCP 47 language tag, or an array of such strings. For the general form and interpretation of the locales argument, see the Intl page. The following Unicode extension key is allowed:

nu
The numbering system to be used. Possible values include: "arab", "arabext", "bali", "beng", "deva", "fullwide", "gujr", "guru", "hanidec", "khmr", "knda", "laoo", "latn", "limb", "mlym", "mong", "mymr", "orya", "tamldec", "telu", "thai", "tibt".
options

Optional. An object with some or all of the following properties:

localeMatcher
The locale matching algorithm to use. Possible values are "lookup" and "best fit"; the default is "best fit". For information about this option, see the Intl page.
style
The formatting style to use. Possible values are "decimal" for plain number formatting, "currency" for currency formatting, and "percent" for percent formatting; the default is "decimal".
currency
The currency to use in currency formatting. Possible values are the ISO 4217 currency codes, such as "USD" for the US dollar, "EUR" for the euro, or "CNY" for the Chinese RMB — see the Current currency & funds code list. There is no default value; if the style is "currency", the currency property must be provided.
currencyDisplay
How to display the currency in currency formatting. Possible values are "symbol" to use a localized currency symbol such as €, "code" to use the ISO currency code, "name" to use a localized currency name such as "dollar"; the default is "symbol".
useGrouping
Whether to use grouping separators, such as thousands separators or thousand/lakh/crore separators. Possible values are true and false; the default is true.

The following properties fall into two groups: minimumIntegerDigits, minimumFractionDigits, and maximumFractionDigits in one group, minimumSignificantDigits and maximumSignificantDigits in the other. If at least one property from the second group is defined, then the first group is ignored.

minimumIntegerDigits
The minimum number of integer digits to use. Possible values are from 1 to 21; the default is 1.
minimumFractionDigits
The minimum number of fraction digits to use. Possible values are from 0 to 20; the default for plain number and percent formatting is 0; the default for currency formatting is the number of minor unit digits provided by the ISO 4217 currency code list (2 if the list doesn't provide that information).
maximumFractionDigits
The maximum number of fraction digits to use. Possible values are from 0 to 20; the default for plain number formatting is the larger of minimumFractionDigits and 3; the default for currency formatting is the larger of minimumFractionDigits and the number of minor unit digits provided by the ISO 4217 currency code list (2 if the list doesn't provide that information); the default for percent formatting is the larger of minimumFractionDigits and 0.
minimumSignificantDigits
The minimum number of significant digits to use. Possible values are from 1 to 21; the default is 1.
maximumSignificantDigits
The maximum number of significant digits to use. Possible values are from 1 to 21; the default is minimumSignificantDigits.

示例

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

var number = 3500;

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

例如:检查支持localesoptions参数

localesoptions参数不是在所有浏览器都支持的。要检查浏览器的实现是否支持它们,如果不支持就直接抛异常了 RangeError 

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

示例:使用 locales

这个例子显示了一些本地化的数字格式的变化。为了让您的应用程序的用户界面中使用的语言格式,请确保指定使用的语言(可能还有一些备用语言)locales的说法:

var number = 123456.789;

// German uses comma as decimal separator and period for thousands
alert(number.toLocaleString("de-DE"));
// → 123.456,789

// Arabic in most Arabic speaking countries uses real Arabic digits
alert(number.toLocaleString("ar-EG"));
// → ١٢٣٤٥٦٫٧٨٩

// India uses thousands/lakh/crore separators
alert(number.toLocaleString("en-IN"));
// → 1,23,456.789

// the nu extension key requests a numbering system, e.g. Chinese decimal
alert(number.toLocaleString("zh-Hans-CN-u-nu-hanidec"));
// → 一二三,四五六.七八九

// when requesting a language that may not be supported, such as
// Balinese, include a fallback language, in this case Indonesian
alert(number.toLocaleString(["ban", "id"]));
// → 123.456,789

示例:使用 options

所提供的结果toLocaleString可以使用自定义options参数:

var number = 123456.789;

// request a currency format
alert(number.toLocaleString("de-DE", {style: "currency", currency: "EUR"}));
// → 123.456,79 €

// the Japanese yen doesn't use a minor unit
alert(number.toLocaleString("ja-JP", {style: "currency", currency: "JPY"}))
// → ¥123,457

// limit to three significant digits
alert(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  

浏览器兼容性

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support (Yes) (Yes) (Yes) (Yes) (Yes)
locales and options arguments 24

29 (29)

11 15 10
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support (Yes) (Yes) (Yes) (Yes) (Yes) (Yes)
locales and options arguments 未实现 26

未实现

bug 864843

未实现 未实现 未实现

相关链接

文档标签和贡献者

 此页面的贡献者: anchengjian, Sivan, quietshu, AlexChao
 最后编辑者: anchengjian,