`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`
    Numbering system. 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"`.
  `ca`
    Calendar. Possible values include: `"buddhist"`, `"chinese"`, `"coptic"`, `"ethioaa"`, `"ethiopic"`, `"gregory"`, `"hebrew"`, `"indian"`, `"islamic"`, `"islamicc"`, `"iso8601"`, `"japanese"`, `"persian"`, `"roc"`.
  `hc`
    Hour cycle. Possible values include: `"h11"`, `"h12"`, `"h23"`, `"h24"`.
`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.
  `timeZone`
    The time zone to use. The only value implementations must recognize is `"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`
    Whether to use 12-hour time (as opposed to 24-hour time). Possible values are `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`
    The hour cycle to use. Possible values are `"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`
    The format matching algorithm to use. Possible values are `"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`
    The representation of the weekday. Possible values are:
    - `"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`
    The representation of the era. Possible values are:
    - `"long"` (e.g., `Anno Domini`)
    - `"short"` (e.g., `AD`)
    - `"narrow"` (e.g., `A`)
  `year`
    The representation of the year. Possible values are:
    - `"numeric"` (e.g., `2012`)
    - `"2-digit"` (e.g., `12`)
  `month`
    The representation of the month. Possible values are:
    - `"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`
    The representation of the day. Possible values are:
    - `"numeric"` (e.g., `1`)
    - `"2-digit"` (e.g., `01`)
  `hour`
    The representation of the hour. Possible values are `"numeric"`, `"2-digit"`.
  `minute`
    The representation of the minute. Possible values are `"numeric"`, `"2-digit"`.
  `second`
    The representation of the second. Possible values are `"numeric"`, `"2-digit"`.
  `timeZoneName`
    The representation of the time zone name. Possible values are:
    - `"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.

Update compatibility data on GitHub

| Desktop | Mobile | Server
| Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | Android webview | Chrome for Android | Edge Mobile | Firefox for Android | Opera for Android | Safari on iOS | Samsung Internet | Node.js
`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 ?

### Legend

Full support
  Full support
No support
  No support
Compatibility unknown
  Compatibility unknown

## 相关链接

- `DateTimeFormat`
- `Date.prototype.toLocaleString()`
- `Date.prototype.toLocaleTimeString()`