Temporal.PlainDateTime.prototype.toLocaleString()

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

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

Синтаксис

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

Параметры

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

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

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

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

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

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

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

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

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

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

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

Исключения

RangeError

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

TypeError

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

Примеры

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

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

const dt = Temporal.PlainDateTime.from("2021-08-01T12:34:56");

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

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

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

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

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

const dt = Temporal.PlainDateTime.from("2021-08-01T12:34:56");
dt.toLocaleString("en-US", { dateStyle: "full", timeStyle: "full" }); // Sunday, August 1, 2021 at 12:34:56 PM
dt.toLocaleString("en-US", {
  year: "numeric",
  month: "long",
  hour: "numeric",
}); // August 2021 at 12 PM
dt.toLocaleString("en-US", {
  year: "numeric",
  hour: "numeric",
  minute: "numeric",
}); // 2021, 12:34 PM

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

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

См. также

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