This page was translated from English by the community.Learn more and join the MDN Web Docs community.
Date.prototype.toLocaleString()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since июль 2015 г..
МетодtoLocaleString() экземпляровDate возвращает строку, содержащую зависимое от языка представление этой даты в локальном часовом поясе. В реализациях, поддерживающихIntl.DateTimeFormat API, этот метод просто вызываетIntl.DateTimeFormat.
При каждом вызовеtoLocaleString происходит поиск по большой базе локализованных строк, что может быть неэффективным. Когда метод вызывается много раз с одинаковыми параметрами, лучше создать объектIntl.DateTimeFormat и использовать его методformat(), потому что объектDateTimeFormat запоминает переданные ему параметры и может кешировать данные, чтобы последующие вызовыformat могли выполнять поиск с более определённым контекстом.
Интерактивный пример
const event = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));// British English uses day-month-year order and 24-hour time without AM/PMconsole.log(event.toLocaleString("en-GB", { timeZone: "UTC" }));// Expected output: "20/12/2012, 03:00:00"// Korean uses year-month-day order and 12-hour time with AM/PMconsole.log(event.toLocaleString("ko-KR", { timeZone: "UTC" }));// Expected output: "2012. 12. 20. 오전 3:00:00"Синтаксис
toLocaleString()toLocaleString(locales)toLocaleString(locales, options)Параметры
Параметрыlocales иoptions изменяют поведение функции и позволяют приложениям определять язык, правила форматирования которого, следует использовать.
В реализациях, поддерживающихIntl.DateTimeFormat API, эти параметры соответствуют параметрам конструктораIntl.DateTimeFormat(). Реализации без поддержкиIntl.DateTimeFormat должны игнорировать оба параметра, используя локаль и формат возвращаемой строки определяемые самой реализацией.
localesНеобязательныйСтрока с языковым тегом BCP 47 или массив таких строк. Соответствует параметру
localesконструктора `Intl.DateTimeFormat().В реализациях без поддержки
Intl.DateTimeFormatэтот параметр игнорируется и обычно используется локаль устройства.optionsНеобязательныйОбъект определяющий выходной формат. Соответствует параметру
optionsконструктораIntl.DateTimeFormat(). ОпцияtimeStyleдолжна бытьundefinedили будет возникатьTypeError. Еслиweekday,year,monthиdayодновременно равныundefined, тоyear,monthиdayбудут установлены в"numeric".В реализациях без поддержки
Intl.DateTimeFormatэтот параметр игнорируется.
Смотрите описаниеконструктораIntl.DateTimeFormat() для подробностей использования этих параметров.
Возвращаемое значение
Строка, представляющая указанную дату в соответствии с языковыми требованиями.
В реализациях с поддержкойIntl.DateTimeFormat результат будет эквивалентнымnew Intl.DateTimeFormat(locales, options).format(date).
Примечание:В большинстве случаев форматирование, возвращаемоеtoLocaleString(), единообразно. Однако результат может быть разным в зависимости от времени, языка и реализации — это допускается спецификацией. Не следует сравнивать результатtoLocaleString() со статическими значениями.
Примеры
ИспользованиеtoLocaleString()
При использовании без указания локали возвращается строка, отформатированная в соответствии с локалью и настройками по умолчанию.
const date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));// Вывод toLocaleString() без параметров зависит от реализации,// локали по умолчанию и часового пояса по умолчаниюconsole.log(date.toLocaleString());// "12/11/2012, 7:00:00 PM", если код запущен с локалью en-US и часовым поясом America/Los_AngelesПроверка поддержки параметровlocales иoptions
Параметрыlocales иoptions могут поддерживаться не во всех реализациях. В реализациях без поддержки интернационализацииtoLocaleString() всегда использует системную локаль, что может оказаться не тем, что вам нужно. Поскольку любая реализация, поддерживающая параметрыlocales иoptions, должна поддерживатьIntl API, проверить наличие последней можно таким способом:
function toLocaleStringSupportsLocales() { return ( typeof Intl === "object" && !!Intl && typeof Intl.DateTimeFormat === "function" );}Использование параметраlocales
Этот пример показывает некоторые локализованные форматы даты и времени. Для получения формата языка, используемого в пользовательском интерфейсе вашего приложения, убедитесь, что вы указали этот язык (и, возможно, несколько запасных языков) используя параметрlocales:
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));// Форматирование ниже предполагает, что местный часовой пояс равен// America/Los_Angeles для локали США// В американском английском используется порядок месяц-день-год// и 12-часовой формат времениconsole.log(date.toLocaleString("en-US"));// "12/19/2012, 7:00:00 PM"// В британском английском используется порядок день-месяц-год// и 24-часовой формат времениconsole.log(date.toLocaleString("en-GB"));// "20/12/2012 03:00:00"// В корейском используется порядок год-месяц-день// и 12-часовой формат времениconsole.log(date.toLocaleString("ko-KR"));// "2012. 12. 20. 오후 12:00:00"// В большинстве арабоязычных стран используют настоящие арабские цифрыconsole.log(date.toLocaleString("ar-EG"));// "٢٠/١٢/٢٠١٢ ٥:٠٠:٠٠ ص"// В Японии приложения могут захотеть использовать японский календарь,// в котором 2012 год является 24-м годом эры Хейсейconsole.log(date.toLocaleString("ja-JP-u-ca-japanese"));// "24/12/20 12:00:00"// Если запрашиваемый язык может не поддерживаться, например// балийский, откатываемся на запасной язык, в данном случае индонезийскийconsole.log(date.toLocaleString(["ban", "id"]));// "20/12/2012 11.00.00"Использование параметраoptions
Результат, предоставляемый методомtoLocaleString(), может быть настроен с помощью параметраoptions:
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));// Запрашиваем день недели вместе с длинным форматом датыvar options = { weekday: "long", year: "numeric", month: "long", day: "numeric",};console.log(date.toLocaleString("de-DE", options));// "Donnerstag, 20. Dezember 2012"// Приложение может захотеть использовать UTC и показать этоoptions.timeZone = "UTC";options.timeZoneName = "short";console.log(date.toLocaleString("en-US", options));// "Thursday, December 20, 2012, GMT"// Иногда даже в США нужен 24-х часовой формат времениconsole.log(date.toLocaleString("en-US", { hour12: false }));// "12/19/2012, 19:00:00"Спецификации
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-date.prototype.tolocalestring |
| ECMAScript® 2026 Internationalization API Specification # sup-date.prototype.tolocalestring |