Intl.DateTimeFormat
===================

Объект **`Intl.DateTimeFormat`** предоставляет возможности форматирования даты и времени в соответствии с языковыми правилами.

Интерактивный пример
--------------------

Конструктор
-----------

`Intl.DateTimeFormat()` (en-US)

Создаёт новый объект `Intl.DateTimeFormat`.

Статические методы
------------------

`Intl.DateTimeFormat.supportedLocalesOf()`

Возвращает массив, содержащий локали, которые поддерживаются без необходимости возврата к локали по умолчанию.

Свойства экземпляра
-------------------

Эти свойства определены в `Intl.DateTimeFormat.prototype` и есть у всех экземпляров `Intl.DateTimeFormat`.

`Intl.DateTimeFormat.prototype.constructor`

Функция-конструктор, создающая экземпляр объекта. Для экземпляров `Intl.DateTimeFormat` начальным значением является конструктор `Intl.DateTimeFormat` (en-US).

`Intl.DateTimeFormat.prototype[@@toStringTag]`

Начальным значением свойства `@@toStringTag` является строка `"Intl.DateTimeFormat"`. Это свойство используется в `Object.prototype.toString()`.

Методы экземпляра
-----------------

`Intl.DateTimeFormat.prototype.format()`

Функция-геттер, которая форматирует дату в соответствии с локалью и настройками форматирования этого объекта `DateTimeFormat`.

`Intl.DateTimeFormat.prototype.formatRange()` (en-US)

Этот метод принимает две даты и форматирует диапазон дат наиболее кратким образом на основе локали и параметров, установленных при создании экземпляра `DateTimeFormat`.

`Intl.DateTimeFormat.prototype.formatRangeToParts()` (en-US)

Этот метод принимает две даты и возвращает массив объектов, которые содержат специфичные для локали токены, представляющие каждую часть отформатированного диапазона дат.

`Intl.DateTimeFormat.prototype.formatToParts()`

Возвращает `массив` объектов, представляющих части даты, которые могут быть использованы для пользовательского форматирования с учётом локали.

`Intl.DateTimeFormat.prototype.resolvedOptions()`

Возвращает новый объект со свойствами, представляющими локаль и настройки форматирования, определённые во время инициализации объекта.

Примеры
-------

### Использование `DateTimeFormat`

При использовании без указания локали `DateTimeFormat` использует локаль и настройки по умолчанию.


```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// результат вызова без аргументов зависит от реализации,
// локали по умолчанию и часового пояса по умолчанию
console.log(new Intl.DateTimeFormat().format(date));
// "12/19/2012", если код запущен с локалью en-US и часовым поясом America/Los\_Angeles
```

### Использование параметра `locales`

Этот пример показывает некоторые локализованные форматы даты и времени. Для получения формата языка, используемого в пользовательском интерфейсе вашего приложения, убедитесь, что вы указали этот язык (и, возможно, несколько запасных языков) используя параметр `locales`:


```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// Форматирование ниже предполагает, что местный часовой пояс равен
// America/Los\_Angeles для локали США

// В американском английском используется порядок месяц-день-год
console.log(new Intl.DateTimeFormat("en-US").format(date));
// "12/19/2012"

// В британском английском используется порядок день-месяц-год
console.log(new Intl.DateTimeFormat("en-GB").format(date));
// "20/12/2012"

// В корейском используется порядок год-месяц-день
console.log(new Intl.DateTimeFormat("ko-KR").format(date));
// "2012. 12. 20."

// В большинстве арабоязычных стран используют настоящие арабские цифры
console.log(new Intl.DateTimeFormat("ar-EG").format(date));
// "٢٠‏/١٢‏/٢٠١٢"

// В Японии приложения могут захотеть использовать японский календарь,
// в котором 2012 год является 24-м годом эры Хейсей
console.log(new Intl.DateTimeFormat("ja-JP-u-ca-japanese").format(date));
// "24/12/20"

// Если запрашиваемый язык может не поддерживаться, например
// балийский, откатываемся на запасной язык, в данном случае индонезийский
console.log(new Intl.DateTimeFormat(["ban", "id"]).format(date));
// "20/12/2012"
```

### Использование параметра `options`

Формат даты и времени может быть настроен с помощью параметра `options`:


```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0, 200));

// Запрашиваем день недели вместе с длинным форматом даты
let options = {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
};
console.log(new Intl.DateTimeFormat("de-DE", options).format(date));
// "Donnerstag, 20. Dezember 2012"

// Приложение может захотеть использовать UTC и показать это
options.timeZone = "UTC";
options.timeZoneName = "short";
console.log(new Intl.DateTimeFormat("en-US", options).format(date));
// "Thursday, December 20, 2012, GMT"

// Иногда требуется большая точность
options = {
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  timeZone: "Australia/Sydney",
  timeZoneName: "short",
};
console.log(new Intl.DateTimeFormat("en-AU", options).format(date));
// "2:00:00 pm AEDT"

// Иногда требуется ещё большая точность
options.fractionalSecondDigits = 3; // количество цифр для отображения долей секунд
console.log(new Intl.DateTimeFormat("en-AU", options).format(date));
// "2:00:00.200 pm AEDT"

// Иногда даже в США нужен 24-часовой формат времени
options = {
  year: "numeric",
  month: "numeric",
  day: "numeric",
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  hour12: false,
  timeZone: "America/Los\_Angeles",
};
console.log(new Intl.DateTimeFormat("en-US", options).format(date));
// "12/19/2012, 19:00:00"

// Для указания настроек, но использования локали по умолчанию, нужно передать undefined
console.log(new Intl.DateTimeFormat(undefined, options).format(date));
// "12/19/2012, 19:00:00"

// Иногда полезно включать время суток
options = { hour: "numeric", dayPeriod: "short" };
console.log(new Intl.DateTimeFormat("en-US", options).format(date));
// 10 at night
```


Форматы календаря и нумерации также можно установить независимо с помощью параметра `options`:


```js
const options = { calendar: "chinese", numberingSystem: "arab" };
const dateFormat = new Intl.DateTimeFormat(undefined, options);
const usedOptions = dateFormat.resolvedOptions();

console.log(usedOptions.calendar);
// "chinese"

console.log(usedOptions.numberingSystem);
// "arab"

console.log(usedOptions.timeZone);
// "America/New\_York" (the users default timezone)
```

Спецификации
------------

| Specification |
| --- |
| ECMAScript Internationalization API Specification # datetimeformat-objects |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* Полифил `Intl.DateTimeFormat` в FormatJS
* `Intl`