Temporal.PlainDate.prototype.toLocaleString()

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

Каждый раз, когда вызывается toLocaleString, ему приходится выполнять поиск в большой базе данных строк локализации, что потенциально неэффективно. Когда метод вызывается много раз с одинаковыми аргументами, лучше создать объект Intl.DateTimeFormat и использовать его метод format(), поскольку объект DateTimeFormat запоминает переданные ему аргументы и может решить кэшировать часть базы данных, чтобы будущие вызовы 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 может иметь любое значение. Относительно параметров компонентов даты и времени и сокращений стиля (dateStyle и timeStyle), параметры должны следовать одной из этих форм:

• Не предоставлять ни одного из них: year, month и day по умолчанию будут "numeric".
• Предоставить только dateStyle: это разворачивается в форматы weekday, era, year, month и day.
• Предоставить некоторые параметры компонентов даты и времени, где по крайней мере один из них является параметром даты (weekday, year, month, day). В выводе будут включены только указанные компоненты даты.

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

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

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

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

Исключения

RangeError

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

TypeError

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

Примеры

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

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

const date = Temporal.PlainDate.from("2021-08-01");

console.log(date.toLocaleString()); // 8/1/2021 (assuming en-US locale)

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

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

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

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

const date = Temporal.PlainDate.from("2021-08-01");
date.toLocaleString("en-US", { dateStyle: "full" }); // Sunday, August 1, 2021
date.toLocaleString("en-US", {
  year: "numeric",
  month: "long",
  day: "numeric",
}); // August 1, 2021
date.toLocaleString("en-US", { year: "numeric", month: "long" }); // August 2021

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

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

См. также

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