date.toLocaleString

toLocaleString()方法返回该日期对象的字符串，该字符串格式因不同语言而不同。新增的参数 locales 和 options 使程序能够指定使用哪种语言格式化规则，允许定制该方法的表现（behavior）。在旧版本浏览器中， locales 和 options 参数被忽略，使用的语言环境和返回的字符串格式是各自独立实现的。

语法

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

参数

查看浏览器兼容性小节，看下哪些浏览器支持 locales 和 options 参数，还可以参看例子：检测 locales和options参数支持情况。

locales

可选的。一个带有BCP 47语言标签的字符串或这种字符串的数组。有关参数的一般形式和解释locales，请参阅Intl页面。以下Unicode扩展键是被允许的：

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"。

options

可选的。具有部分或全部以下属性的对象：

localeMatcher要使用的语言环境匹配算法。可能的值是"lookup"和"best fit"; 默认是"best fit"。有关此选项的信息，请参阅Intl页面。

timeZone要使用的时区。唯一的价值实现必须认识到的是"UTC"; 默认是运行时的默认时区。实现也可以识别的时区名称IANA时区数据库，如"Asia/Shanghai"，"Asia/Kolkata"，"America/New_York"。

hour12是否使用12小时的时间（而不是24小时的时间）。可能的值是true和false; 默认值是语言环境相关的。

formatMatcher要使用的格式匹配算法。可能的值是"basic"和"best fit"; 默认是"best fit"。有关使用此属性的信息，请参阅以下段落。

以下属性描述了格式化输出中使用的日期时间组件以及它们所需的表示。实现需要至少支持以下子集：

• 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"。

year年的表示。可能的值是"numeric"，"2-digit"。

month月份的表示。可能的值是"numeric"，"2-digit"，"narrow"，"short"，"long"。

day一天的表示。可能的值是"numeric"，"2-digit"。

hour小时的表示。可能的值是"numeric"，"2-digit"。

minute分钟的表示。可能的值是"numeric"，"2-digit"。

second第二个的表示。可能的值是"numeric"，"2-digit"。

timeZoneName时区名称的表示。可能的值是"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	?	?	?