Temporal.ZonedDateTime.prototype.toLocaleString()

Метод toLocaleString() экземпляров Temporal.ZonedDateTime возвращает строку с зависящим от языка представлением этой даты и времени. В реализациях с поддержкой API Intl.DateTimeFormat этот метод делегирует Intl.DateTimeFormat и передает эту дату-время, преобразованную в Temporal.Instant (поскольку Intl.DateTimeFormat не может напрямую форматировать Temporal.ZonedDateTime).

Каждый раз, когда вызывается toLocaleString, ему приходится выполнять поиск в большой базе данных строк локализации, что потенциально неэффективно. Когда метод вызывается много раз с одними и теми же аргументами, лучше создать объект Intl.DateTimeFormat и использовать его метод format(), потому что объект DateTimeFormat запоминает переданные ему аргументы и может решить кэшировать часть базы данных, чтобы будущие вызовы format могли искать строки локализации в более ограниченном контексте. Однако в настоящее время Intl.DateTimeFormat не поддерживает форматирование объектов Temporal.ZonedDateTime, поэтому вы должны сначала преобразовать их в объекты Temporal.Instant, прежде чем передавать их в format().

Синтаксис

toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)

Параметры

Параметры locales и options настраивают поведение функции и позволяют приложениям указывать язык, чьи соглашения о форматировании должны использоваться.

В реализациях, которые поддерживают API Intl.DateTimeFormat, эти параметры точно соответствуют параметрам конструктора Intl.DateTimeFormat(). Реализации без поддержки Intl.DateTimeFormat возвращают точно ту же строку, что и toString(), игнорируя оба параметра.

locales Необязательно

Строка с языковым тегом BCP 47 или массив таких строк. Соответствует параметру locales конструктора Intl.DateTimeFormat().

options Необязательно

Объект, настраивающий формат вывода. Соответствует параметру options конструктора Intl.DateTimeFormat(). Если календарь этой даты-времени не является "iso8601", опция calendar должна быть предоставлена с тем же значением; в противном случае, если календарь этой даты-времени является "iso8601", опция calendar может быть любым значением. Опция timeZone не должна быть предоставлена, так как она автоматически устанавливается как timeZoneId даты-времени. Что касается опций компонентов даты-времени и сокращений стиля (dateStyle и timeStyle), опции должны следовать одной из этих форм:

• Не предоставлять ни одну из них: year, month, day, hour, minute и second по умолчанию будут установлены в "numeric".
• Предоставить хотя бы одну из dateStyle или timeStyle: компоненты даты-времени будут установлены в соответствии с указанным стилем и локалью.
• Предоставить некоторые опции компонентов даты-времени. В вывод будут включены только указанные компоненты даты-времени.

Подробности об этих параметрах и способах их использования см. в конструкторе Intl.DateTimeFormat().

Возвращаемое значение

Строка, представляющая заданную дату-время в соответствии с языковыми соглашениями.

В реализациях с Intl.DateTimeFormat это эквивалентно new Intl.DateTimeFormat(locales, { ...options, timeZone: dateTime.timeZoneId }).format(dateTime.toInstant()), где options был нормализован, как описано выше.

Исключения

RangeError

Выбрасывается, если любая из опций недействительна.

TypeError

Выбрасывается, если любая из опций не имеет ожидаемого типа.

Примеры

Использование toLocaleString()

Базовое использование этого метода без указания locale возвращает отформатированную строку в локали по умолчанию и с настройками по умолчанию.

const zdt = Temporal.ZonedDateTime.from(
  "2021-08-01T12:34:56-04:00[America/New_York]",
);

console.log(zdt.toLocaleString()); // 8/1/2021, 12:34:56 PM EDT (assuming en-US locale)

Если календарь даты не соответствует календарю по умолчанию для локали, и календарь даты не является iso8601, необходимо явно предоставить опцию calendar с тем же значением.

const zdt = Temporal.ZonedDateTime.from(
  "2021-08-01T12:34:56+09:00[Asia/Tokyo][u-ca=japanese]",
);
// The ja-JP locale uses the Gregorian calendar by default
zdt.toLocaleString("ja-JP", { calendar: "japanese" }); // R3/8/1 12:34:56 JST

Использование toLocaleString() с опциями

Вы можете настроить, какие части даты будут включены в вывод, предоставив параметр options.

const zdt = Temporal.ZonedDateTime.from(
  "2021-08-01T12:34:56+09:00[Asia/Tokyo][u-ca=japanese]",
);
zdt.toLocaleString("ja-JP", {
  calendar: "japanese",
  dateStyle: "full",
  timeStyle: "full",
}); // 令和3年8月1日日曜日 12時34分56秒 日本標準時
zdt.toLocaleString("ja-JP", {
  calendar: "japanese",
  year: "numeric",
  month: "long",
  hour: "numeric",
  timeZoneName: "shortGeneric",
}); // 令和3年8月 12時 JST
zdt.toLocaleString("ja-JP", {
  calendar: "japanese",
  year: "numeric",
  hour: "numeric",
  minute: "numeric",
}); // 令和3年 12:34

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

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

См. также

• Temporal.ZonedDateTime
• Intl.DateTimeFormat
• Temporal.ZonedDateTime.prototype.toJSON()
• Temporal.ZonedDateTime.prototype.toString()