Temporal.PlainYearMonth.prototype.toLocaleString()

Метод toLocaleString() экземпляров Temporal.PlainYearMonth возвращает строку с зависящим от языка представлением этого года-месяца. В реализациях с поддержкой 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(). Опция calendar должна быть предоставлена с тем же значением, что и календарь этого года-месяца. Что касается опций компонентов даты и времени и сокращений стилей (dateStyle и timeStyle), опции должны соответствовать одной из следующих форм:

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

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

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

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

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

Исключения

RangeError

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

TypeError

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

Примеры

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

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

// Note that just specifying "2021-08" defaults to the ISO 8601 calendar,
// which throws an error if the locale's default calendar is not ISO 8601.
const ym = Temporal.PlainYearMonth.from("2021-08-01[u-ca=gregory]");

console.log(ym.toLocaleString()); // 8/2021 (assuming en-US locale and Gregorian calendar)

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

const ym = Temporal.PlainYearMonth.from("2021-08");
ym.toLocaleString("en-US", { calendar: "iso8601" }); // 2021-08

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

Вы можете настроить, какие части года-месяца включены в вывод, предоставив параметр options.

const ym = Temporal.PlainYearMonth.from("2021-08-01[u-ca=gregory]");
ym.toLocaleString("en-US", { dateStyle: "full" }); // August 2021
ym.toLocaleString("en-US", { year: "2-digit" }); // 21
ym.toLocaleString("en-US", { month: "long" }); // August

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

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

См. также

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