toLocaleDateString()
方法返回该日期对象日期部分的字符串,该字符串格式因不同语言而不同。新增的参数 locales
和 options
使程序能够指定使用哪种语言格式化规则,允许定制该方法的表现(behavior)。在旧版本浏览器中, locales
和 options
参数被忽略,使用的语言环境和返回的字符串格式是各自独立实现的。
The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.
dateObj.toLocaleDateString([locales [, options]])
查看浏览器兼容性小节,看下哪些浏览器支持 locales
和 options
参数,还可以参看例子: 检测 locales
和 options
参数支持情况。
locales
Optional. A string with a BCP 47 language tag, or an array of such strings. Unicode extension are supported (for example "en-US-u-ca-buddhist"
). For the general form and interpretation of the locales
argument, see the Intl page. The following Unicode extension keys are allowed:
nu
"arab"
, "arabext"
, "bali"
, "beng"
, "deva"
, "fullwide"
, "gujr"
, "guru"
, "hanidec"
, "khmr"
, "knda"
, "laoo"
, "latn"
, "limb"
, "mlym"
, "mong"
, "mymr"
, "orya"
, "tamldec"
, "telu"
, "thai"
, "tibt"
.ca
"buddhist"
, "chinese"
, "coptic"
, "ethioaa"
, "ethiopic"
, "gregory"
, "hebrew"
, "indian"
, "islamic"
, "islamicc"
, "iso8601"
, "japanese"
, "persian"
, "roc"
.hc
"h11"
, "h12"
, "h23"
, "h24"
.options
Optional. An object with some or all of the following properties:
localeMatcher
"lookup"
and "best fit"
; the default is "best fit"
. For information about this option, see the Intl page.timeZone
"UTC"
; the default is the runtime's default time zone. Implementations may also recognize the time zone names of the IANA time zone database, such as "Asia/Shanghai"
, "Asia/Kolkata"
, "America/New_York"
.hour12
true
and false
; the default is locale dependent. This option overrides the hc
language tag and/or the hourCycle
option in case both are present.hourCycle
"h11"
, "h12"
, "h23"
, or "h24"
. This option overrides the hc
language tag, if both are present, and the hour12
option takes precedence in case both options have been specified.formatMatcher
"basic"
and "best fit"
; the default is "best fit"
. See the following paragraphs for information about the use of this property.The following properties describe the date-time components to use in formatted output, and their desired representations. Implementations are required to support at least the following subsets:
weekday
, year
, month
, day
, hour
, minute
, second
weekday
, year
, month
, day
year
, month
, day
year
, month
month
, day
hour
, minute
, second
hour
, minute
Implementations may support other subsets, and requests will be negotiated against all available subset-representation combinations to find the best match. Two algorithms are available for this negotiation and selected by the formatMatcher
property: A fully specified "basic"
algorithm and an implementation-dependent "best fit"
algorithm.
weekday
"long"
(e.g., Thursday
)"short"
(e.g., Thu
)"narrow"
(e.g., T
). Two weekdays may have the same narrow style for some locales (e.g. Tuesday
's narrow style is also T
).era
"long"
(e.g., Anno Domini
)"short"
(e.g., AD
)"narrow"
(e.g., A
)year
"numeric"
(e.g., 2012
)"2-digit"
(e.g., 12
)month
"numeric"
(e.g., 2
)"2-digit"
(e.g., 02
)"long"
(e.g., March
)"short"
(e.g., Mar
)"narrow"
(e.g., M
). Two months may have the same narrow style for some locales (e.g. May
's narrow style is also M
).day
"numeric"
(e.g., 1
)"2-digit"
(e.g., 01
)hour
"numeric"
, "2-digit"
.minute
"numeric"
, "2-digit"
.second
"numeric"
, "2-digit"
.timeZoneName
"long"
(e.g., British Summer Time
)"short"
(e.g., GMT+1
)The default value for each date-time component property is undefined
, but if the weekday
, year
, month
, day
properties are all undefined
, then year
, month
, and day
are assumed to be "numeric".
toLocaleDateString
没有指定语言环境(locale)时,返回一个使用默认语言环境和格式设置(options)的格式化字符串。
var date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));
// toLocaleDateString without arguments depends on the implementation,
// the default locale, and the default time zone
date.toLocaleDateString();
// → "12/11/2012" if run in en-US locale with time zone America/Los_Angeles
locales
和 options
参数支持情况locales
和 options
参数不是所有的浏览器都支持。为了检测一种实现环境(implementation)是否支持它们,可以使用不合法的语言标签,如果实现环境支持该参数,则会抛出一个 RangeError
异常,反之会忽略参数。
function toLocaleDateStringSupportsLocales() {
try {
new Date().toLocaleDateString("i");
} catch (e) {
return e.name === "RangeError";
}
return false;
}
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
alert(date.toLocaleDateString("en-US"));
// → "12/19/2012"
// British English uses day-month-year order
alert(date.toLocaleDateString("en-GB"));
// → "20/12/2012"
// Korean uses year-month-day order
alert(date.toLocaleDateString("ko-KR"));
// → "2012. 12. 20."
// Arabic in most Arabic speaking countries uses real Arabic digits
alert(date.toLocaleDateString("ar-EG"));
// → "٢٠/١٢/٢٠١٢"
// for Japanese, applications may want to use the Japanese calendar,
// where 2012 was the year 24 of the Heisei era
alert(date.toLocaleDateString("ja-JP-u-ca-japanese"));
// → "24/12/20"
// when requesting a language that may not be supported, such as
// Balinese, include a fallback language, in this case Indonesian
alert(date.toLocaleDateString(["ban", "id"]));
// → "20/12/2012"
options
可以使用 options
参数来自定义 toLocaleDateString
方法返回的字符串。
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"};
alert(date.toLocaleDateString("de-DE", options));
// → "Donnerstag, 20. Dezember 2012"
// an application may want to use UTC and make that visible
options.timeZone = "UTC";
options.timeZoneName = "short";
alert(date.toLocaleDateString("en-US", options));
// → "Thursday, December 20, 2012, GMT"
当格式化大量日期时,最好创建一个 Intl.DateTimeFormat
对象,然后使用该对象 format
属性提供的方法。
规范版本 | 规范状态 | 注解 |
---|---|---|
ECMAScript 3rd Edition. Implemented in JavaScript 1.0 | Standard | Initial definition. |
ECMAScript 5.1 (ECMA-262) Date.prototype.toLocaleDateString |
Standard | |
ECMAScript 2015 (6th Edition, ECMA-262) Date.prototype.toLocaleDateString |
Standard | |
ECMAScript Internationalization API Specification, 1st Edition | Standard | Defines locales and options arguments. |
The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Desktop | Mobile | Server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
toLocaleDateString | Chrome Full support Yes | Edge Full support 12 | Firefox Full support 1 | IE Full support Yes | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Edge Mobile Full support Yes | Firefox Android Full support 4 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes | nodejs ? |
locales | Chrome Full support 24 | Edge Full support 12 | Firefox Full support 29 | IE Full support 11 | Opera Full support 15 | Safari Full support 10 | WebView Android No support No | Chrome Android Full support 26 | Edge Mobile ? | Firefox Android Full support 56 | Opera Android No support No | Safari iOS Full support 10 | Samsung Internet Android Full support Yes | nodejs ? |
options | Chrome Full support 24 | Edge Full support 12 | Firefox Full support 29 | IE Full support 11 | Opera Full support 15 | Safari Full support 10 | WebView Android No support No | Chrome Android Full support 26 | Edge Mobile ? | Firefox Android Full support 56 | Opera Android No support No | Safari iOS Full support 10 | Samsung Internet Android Full support Yes | nodejs ? |
IANA time zone names in timeZone option | Chrome Full support 24 | Edge Full support 14 | Firefox Full support 52 | IE ? | Opera ? | Safari ? | WebView Android ? | Chrome Android ? | Edge Mobile ? | Firefox Android No support No | Opera Android ? | Safari iOS ? | Samsung Internet Android ? | nodejs ? |