Intl.DateTimeFormat: примеры (JAVASCRIPT)

Примеры использования

Простой пример с локалью по умолчанию:

new Intl.DateTimeFormat().format(new Date('2024-01-15'))

"15.01.2024" (результат для локали ru-RU)

Использование явного указания локали:

new Intl.DateTimeFormat('en-US').format(new Date('2024-01-15'))

"1/15/2024"

Применение опций для кастомизации:

new Intl.DateTimeFormat('ru-RU', {
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
}).format(new Date('2024-01-15'))

"понедельник, 15 января 2024 г."

Форматирование времени с часовым поясом:

new Intl.DateTimeFormat('ru-RU', {
  hour: 'numeric',
  minute: 'numeric',
  timeZone: 'America/New_York',
  timeZoneName: 'short'
}).format(new Date('2024-01-15T10:30:00Z'))

"05:30 EST"

Использование dateStyle и timeStyle:

new Intl.DateTimeFormat('ru-RU', {
  dateStyle: 'full',
  timeStyle: 'long'
}).format(new Date('2024-01-15T10:30:00'))

"понедельник, 15 января 2024 г., 10:30:00 GMT+3"

Похожие функции в JavaScript

Date.prototype.toLocaleDateString() / toLocaleTimeString() / toLocaleString(): Упрощенные методы для форматирования дат и времени. Используют те же аргументы locales и options, что и Intl.DateTimeFormat. Предпочтительны для простых случаев, когда не требуется повторное использование объекта форматирования.

Moment.js (и другие библиотеки): Библиотеки для работы с датами, предлагающие расширенные возможности парсинга, валидации, манипуляций и форматирования. Intl.DateTimeFormat является нативной альтернативой для задач форматирования, не требуя подключения сторонних библиотек.

Выбор зависит от задачи: для сложных манипуляций с датами могут подойти библиотеки, а для интернационализации форматирования нативная Intl API обычно эффективнее.

Альтернативы в других языках

PHP

Функция IntlDateFormatter из расширения intl.

$formatter = new IntlDateFormatter('ru_RU', IntlDateFormatter::FULL, IntlDateFormatter::FULL);
echo $formatter->format(new DateTime('2024-01-15 10:30:00'));

"понедельник, 15 января 2024 г., 10:30:00 Московское стандартное время"

Python

Модуль locale и метод strftime.

import locale
from datetime import datetime
locale.setlocale(locale.LC_TIME, 'ru_RU.UTF-8')
print(datetime(2024, 1, 15).strftime('%A, %d %B %Y'))

"понедельник, 15 января 2024"

MySQL

Функция DATE_FORMAT().

SELECT DATE_FORMAT('2024-01-15', '%W, %d %M %Y');

"Monday, 15 January 2024"

C#

Метод ToString с указанием формата и культуры.

DateTime.Now.ToString("D", new System.Globalization.CultureInfo("ru-RU"));

"15 января 2024 г."

Основное отличие JavaScript функции - её интеграция в стандарт ECMAScript и использование объектов Intl, что обеспечивает единообразие в браузерах и среде Node.js.

Типичные ошибки

Передача строки даты вместо объекта Date в метод format.

new Intl.DateTimeFormat('ru-RU').format('2024-01-15');

RangeError: Invalid time value

Указание несуществующего часового пояса.

new Intl.DateTimeFormat('ru-RU', { timeZone: 'Неизвестный/Пояс' }).format(new Date());

RangeError: Invalid time zone specified

Некорректная локаль в массиве locales может привести к использованию локали по умолчанию, а не к ошибке.

new Intl.DateTimeFormat(['xx-YY']).format(new Date());

Форматирование будет выполнено в локали по умолчанию.

Использование устаревших или нестандартных опций может не дать ожидаемого эффекта. Следует сверяться с актуальной спецификацией.

Изменения в последних версиях

В спецификации ECMAScript 2020 (ES11) были добавлены свойства dateStyle и timeStyle, которые упрощают задание предопределенных форматов.

Метод formatRange(startDate, endDate) для форматирования диапазонов дат стал доступен в ES2021 (ES12).

Поддержка новых значений для опций, таких как dayPeriod, и улучшение работы с часовыми поясами продолжает развиваться в современных браузерах и средах выполнения.

Расширенные примеры

Использование метода formatToParts для анализа частей отформатированной строки:

const formatter = new Intl.DateTimeFormat('ru-RU', { month: 'long', day: 'numeric' });
console.log(formatter.formatToParts(new Date('2024-01-15')));

[
  { type: 'day', value: '15' },
  { type: 'literal', value: ' ' },
  { type: 'month', value: 'января' }
]

Форматирование диапазона дат:

const formatter = new Intl.DateTimeFormat('ru-RU', { dateStyle: 'long' });
console.log(formatter.formatRange(
  new Date('2024-01-01'),
  new Date('2024-01-15')
));

"1–15 января 2024 г."

Кастомизация с использованием календаря:

new Intl.DateTimeFormat('ja-JP-u-ca-japanese', {
  era: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
}).format(new Date('2024-01-15'))

"令和6年1月15日"

Форматирование с 12-часовым временем и периодом дня:

new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: '2-digit',
  hour12: true,
  dayPeriod: 'short'
}).format(new Date('2024-01-15T20:30:00'))

"8:30 PM"

Настройка формата с использованием numberingSystem:

new Intl.DateTimeFormat('ar-EG', {
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  numberingSystem: 'arab'
}).format(new Date('2024-01-15'))

"١٥ يناير ٢٠٢٤"

Использование localeMatcher:

// При недоступной локали 'ru-RU' будет использована 'en-US'
new Intl.DateTimeFormat(['ru-RU', 'en-US'], {
  dateStyle: 'full'
}).format(new Date('2024-01-15'))

"Monday, January 15, 2024" (если ru-RU не поддерживается)