`Intl.DateTimeFormat`是根据语言来格式化日期和时间的对象的构造器。

交互示例的源代码存储在 GitHub 资源库。如果你愿意分布交互示例，请复制https://github.com/mdn/interactive-examples，并向我们发送一个pull请求。

## 语法

    new Intl.DateTimeFormat([locales[, options]])
    Intl.DateTimeFormat.call(this[, locales[, options]])

### 参数

`locales`

  可选.缩写语言代码(BCP 47 language tag,例如:cmn-Hans-CN)的字符串或者这些字符串组成的数组. 关于参数locales的一般形式和解释请参见Intl page. 下面的这些Unicode扩展键也是被允许的:

  译者注:下面这两种扩展的使用方式是language[-scripts][-region]-u-nu-* 和 language[-scripts][-region]-u-ca-* ,例如:zh-u-nu-hanidec(表示中文十进制数字) 和 zh-u-ca-chinese(表示中国日历,比如壬辰年冬月8日) ,也可以 nu 和 ca 组合使用 比如 使用 zh-u-ca-chinese-nu-hanidec 格式化Date.now()的返回值类似于"丙申年冬月九日"

  `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`
    使用的local的匹配算法. 可能的值有"lookup"和"best fit"; 默认值是 `"best fit"`. 有关此选项的信息, 请参见Intl page.
  `timeZone`
    使用的时区. 这唯一的值实现必须被标准世界时间(UTC)所识别。默认值是运行时的默认时区. IANA time zone database中的时区名称可能会被识别, 例如`"Asia/Shanghai"`, `"Asia/Kolkata"`, `"America/New_York"`.
  `hour12`
    是否使用12小时时间制(而不是24小时的时间). 可能的值是`true` 或 `false`; 默认值是根据locale来自动决定的(译者注:中国地区的默认值为true).
  `formatMatcher`
    `format的匹配算法.可能的值有"basic"和"best fit";默认值是"best fit".有关此属性使用的信息，参见以下段落。`

    日期时间插件被格式化输出时可以使用的属性集合描述。实现需要支持是以下子集中的其中一个(译者注:当weekday,year等这些属性一个也不使用的时候,在cmn-Hans-CN中相当于使用集合year, month, day, hour, minute, second并且它们的值都是numeric)：

  - `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`,但是若所有的组件属性都是`undefined`,那么`year`, `month`, and `day` 的值就都被认为是"`numeric`".

## 描述

### 属性

`Intl.DateTimeFormat.prototype`
  允许将属性添加到所有对象上。

### 方法

`Intl.DateTimeFormat.supportedLocalesOf()`
  Returns an array containing those of the provided locales that are supported without having to fall back to the runtime's default locale.

## `DateTimeFormat` 实例

### 属性

`DateTimeFormat实例集成以下原型的属性`:

`Intl.DateTimeFormat.prototype.constructor`
  A reference to `Intl.DateTimeFormat`.

### 方法

`DateTimeFormat实例集成以下原型的方法`:

`Intl.DateTimeFormat.prototype.format()`
  Getter function that formats a date according to the locale and formatting options of this `DateTimeFormat` object.

`Intl.DateTimeFormat.prototype.formatToParts()`
  Returns an `Array` of objects representing the date string in parts that can be used for custom locale-aware formatting.
`Intl.DateTimeFormat.prototype.resolvedOptions()`
  Returns a new object with properties reflecting the locale and formatting options computed during initialization of the object.

## 实例

### 使用 `DateTimeFormat`

不指定locale时,DateTimeFormat使用默认的locale 和 默认的 options

    var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

    //参数未填时使用默认的locale和默认的时区
    console.log(new Intl.DateTimeFormat().format(date));
    //如果是在洛杉矶那么值为 → "12/19/2012"

### 使用`locales`

这个例子显示了本地化日期和时间格式的一些变化。为了获得用于您的应用程序的用户界面的语言格式，请确保使用locales参数确保指定语言（可能还有一些回退语言）：

    var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

    // 下面是假定的所在时区
    // 洛杉矶(America/Los_Angeles for the US)

    // 美式英语(US English) 使用  month-day-year 格式
    console.log(new Intl.DateTimeFormat('en-US').format(date));
    // → "12/19/2012"

    // 英式英语(British English) 使用 day-month-year 格式
    console.log(new Intl.DateTimeFormat('en-GB').format(date));
    // → "20/12/2012"

    // 韩国使用 year-month-day 格式
    console.log(new Intl.DateTimeFormat('ko-KR').format(date));
    // → "2012. 12. 20."

    //大部分阿拉伯国家使用阿拉伯字母(real Arabic digits)
    console.log(new Intl.DateTimeFormat('ar-EG').format(date));
    // → "٢٠‏/١٢‏/٢٠١٢"

    //在日本，应用可能想要使用日本日历,
    //2012 是平成24年（平成是是日本天皇明仁的年号,由1989年1月8日起开始计算直至现在）
    console.log(new Intl.DateTimeFormat('ja-JP-u-ca-japanese').format(date));
    // → "平成24/12/20"

    //当请求一个语言可能不支持，如巴厘(ban)，若有备用的语言印尼语(id)，
    //那么将使用印尼语(id)
    console.log(new Intl.DateTimeFormat(['ban', 'id']).format(date));
    // → "20/12/2012"

### 使用`options`

可以使用 `options` 参数来自定义 日期时间格式化方法返回的字符串。

    var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

    //请求参数(options)中包含参数星期(weekday)，并且该参数的值为长类型(long)
    var options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
    console.log(new Intl.DateTimeFormat('de-DE', options).format(date));
    // → "Donnerstag, 20. Dezember 2012"

    // 一个应用使用 世界标准时间(UTC),并且UTC使用短名字(short)展示
    options.timeZone = 'UTC';
    options.timeZoneName = 'short';//若不写这一行那么仍然显示的是世界标准时间；但是GMT三个字母不会显示
    console.log(new Intl.DateTimeFormat('en-US', options).format(date));
    // → "Thursday, December 20, 2012, GMT"

    // 有时你想变得更精确
    options = {
      hour: 'numeric', minute: 'numeric', second: 'numeric',
      timeZoneName: 'short'
    };
    console.log(new Intl.DateTimeFormat('en-AU', options).format(date));
    // → "2:00:00 pm AEDT"

    // 使用24小时制
    options = {
      year: 'numeric', month: 'numeric', day: 'numeric',
      hour: 'numeric', minute: 'numeric', second: 'numeric',
      hour12: false
    };
    console.log(date.toLocaleString('en-US', options));
    // → "12/19/2012, 19:00:00"

## 规范

规范版本 | 规范状态 | 注解
--- | --- | ---
ECMAScript Internationalization API 1.0 (ECMA-402) Intl.DateTimeFormat | Standard | Initial definition.
ECMAScript Internationalization API 2.0 (ECMA-402) Intl.DateTimeFormat | Standard |
ECMAScript Internationalization API 4.0 (ECMA-402) Intl.DateTimeFormat | Draft |

## 浏览器兼容性

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

- Desktop
- Mobile

Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit)
--- | --- | --- | --- | --- | ---
Basic support | 24 | 29 (29) | 11 | 15 | 10

Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Phone | Opera Mobile | Safari Mobile
--- | --- | --- | --- | --- | --- | ---
Basic support | 未实现 | 26 | 未实现 | 未实现 | 未实现 | 10

## 相关链接

- Introduction: The ECMAScript Internationalization API
- Constructors
  - `Intl.Collator`
  - `Intl.DateTimeFormat`
  - `Intl.ListFormat`
  - `Intl.NumberFormat`
  - `Intl.PluralRules`
  - `Intl.RelativeTimeFormat`
- Methods
  - `String.prototype.localeCompare()`
  - `Number.prototype.toLocaleString()`
  - `Date.prototype.toLocaleString()`
  - `Date.prototype.toLocaleDateString()`
  - `Date.prototype.toLocaleTimeString()`