date.toLocaleString
date.toLocaleString
toLocaleString()
方法返回该日期对象的字符串,该字符串格式因不同语言而不同。新增的参数 locales
和 options
使程序能够指定使用哪种语言格式化规则,允许定制该方法的表现(behavior)。在旧版本浏览器中, locales
和 options
参数被忽略,使用的语言环境和返回的字符串格式是各自独立实现的。
语法
dateObj.toLocaleString([locales[, options]])
参数
查看浏览器兼容性小节,看下哪些浏览器支持 locales
和 options
参数,还可以参看例子:检测 locales
和options
参数支持情况。
locales
可选的。一个带有BCP 47语言标签的字符串或这种字符串的数组。有关参数的一般形式和解释locales
,请参阅Intl页面。以下Unicode扩展键是被允许的:
nu
编号系统。可能的值包括:
可选的。具有部分或全部以下属性的对象:
localeMatcher
要使用的语言环境匹配算法。可能的值是"lookup"
和"best fit"
; 默认是"best fit"
。有关此选项的信息,请参阅Intl页面。
以下属性描述了格式化输出中使用的日期时间组件以及它们所需的表示。实现需要至少支持以下子集:
weekday
,year
,month
,day
,hour
,minute
,second
weekday
,year
,month
,day
year
,month
,day
year
,month
month
,day
hour
,minute
,second
hour
,minute
实现可以支持其他子集,并且将针对所有可用的子集表示组合来协商请求以找到最佳匹配。两种算法可用于此协商并由formatMatcher
属性选择:完全指定的"basic"
算法和依赖于实现的"best fit"
算法。
weekday
周日的表示。可能的值是"narrow"
,"short"
,"long"
。era
时代的代表。可能的值是"narrow"
,"short"
,"long"
。
每个日期时组件属性的默认值是undefined
,但如果weekday
,year
,month
,day
,hour
,minute
,second
性质都是undefined
,然后year
,month
,day
,hour
,minute
,和second
被认为是"numeric"
。
返回值
根据语言特定的约定表示给定日期的字符串。
例子
Using toLocaleString()
在没有指定语言环境的基本使用中,返回默认语言环境中的带有默认选项的格式化字符串。
var date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0)
// toLocaleString() without arguments depends on the implementation,
// the default locale, and the default time zone
console.log(date.toLocaleString()
// → "12/11/2012, 7:00:00 PM" if run in en-US locale with time zone America/Los_Angeles
检测 locales 和 options 参数支持情况
locales
和 options
参数不是所有的浏览器都支持。为了检测一种实现环境(implementation)是否支持它们,可以使用不合法的语言标签,如果实现环境支持该参数,则会抛出一个 RangeError
异常,反之会忽略参数。
function toLocaleStringSupportsLocales() {
try {
new Date().toLocaleString('i'
} catch (e) {
return e instanceof RangeError;
}
return false;
}
Using locales
下例展示了本地化日期格式的一些变化。为了在应用的用户界面得到某种语言的日期和时间格式,必须确保使用 locales
参数指定了该语言(可能还需要设置某些回退语言)。
var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0)
// formats below assume the local time zone of the locale;
// America/Los_Angeles for the US
// US English uses month-day-year order and 12-hour time with AM/PM
console.log(date.toLocaleString('en-US')
// → "12/19/2012, 7:00:00 PM"
// British English uses day-month-year order and 24-hour time without AM/PM
console.log(date.toLocaleString('en-GB')
// → "20/12/2012 03:00:00"
// Korean uses year-month-day order and 12-hour time with AM/PM
console.log(date.toLocaleString('ko-KR')
// → "2012. 12. 20. 오후 12:00:00"
// Arabic in most Arabic speaking countries uses real Arabic digits
console.log(date.toLocaleString('ar-EG')
// → "٢٠/١٢/٢٠١٢ ٥:٠٠:٠٠ ص"
// for Japanese, applications may want to use the Japanese calendar,
// where 2012 was the year 24 of the Heisei era
console.log(date.toLocaleString('ja-JP-u-ca-japanese')
// → "24/12/20 12:00:00"
// when requesting a language that may not be supported, such as
// Balinese, include a fallback language, in this case Indonesian
console.log(date.toLocaleString(['ban', 'id'])
// → "20/12/2012 11.00.00"
Using options
可以使用 options
参数来自定义 toLocaleString
方法返回的字符串。
var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0)
// request a weekday along with a long date
var options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
console.log(date.toLocaleString('de-DE', options)
// → "Donnerstag, 20. Dezember 2012"
// an application may want to use UTC and make that visible
options.timeZone = 'UTC';
options.timeZoneName = 'short';
console.log(date.toLocaleString('en-US', options)
// → "Thursday, December 20, 2012, GMT"
// sometimes even the US needs 24-hour time
console.log(date.toLocaleString('en-US', { hour12: false })
// → "12/19/2012, 19:00:00"
性能
格式化大量日期时,最好创建一个Intl.DateTimeFormat
对象并使用其format
属性提供的功能。
规格
Specification | Status | Comment |
---|---|---|
ECMAScript 1st Edition (ECMA-262) | Standard | Initial definition. Implemented in JavaScript 1.0. |
ECMAScript 5.1 (ECMA-262)The definition of 'Date.prototype.toLocaleString' in that specification. | Standard | |
ECMAScript 2015 (6th Edition, ECMA-262)The definition of 'Date.prototype.toLocaleString' in that specification. | Standard | |
ECMAScript Latest Draft (ECMA-262)The definition of 'Date.prototype.toLocaleString' in that specification. | Living Standard | |
ECMAScript Internationalization API 1.0 (ECMA-402)The definition of 'Date.prototype.toLocaleString' in that specification. | Standard | Defines locales and options arguments. |
ECMAScript Internationalization API 2.0 (ECMA-402)The definition of 'Date.prototype.toLocaleString' in that specification. | Standard | |
ECMAScript Internationalization API 4.0 (ECMA-402)The definition of 'Date.prototype.toLocaleString' in that specification. | Draft | |
浏览器兼容性
Feature | Chrome | Edge | Firefox | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|---|
Basic Support | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
locales | 24 | ? | 29 | 11 | 15 | 10 |
options | 24 | ? | 29 | 11 | 15 | 10 |
IANA time zone names in timeZone option | 24 | ? | 52 | ? | ? | ? |
Feature | Android | Chrome for Android | Edge mobile | Firefox for Android | IE mobile | Opera Android | iOS Safari |
---|---|---|---|---|---|---|---|
Basic Support | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
locales | No | 26 | ? | No | No | No | 10 |
options | No | 26 | ? | No | No | No | 10 |
IANA time zone names in timeZone option | ? | ? | ? | No | ? | ? | ? |