Date.prototype.toLocaleString()

Метод toLocaleString() экземпляров Date возвращает строку с зависящим от языка представлением этой даты в локальном часовом поясе. В реализациях с поддержкой API Intl.DateTimeFormat этот метод делегирует 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/PM
console.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/PM
console.log(event.toLocaleString("ko-KR", { timeZone: "UTC" }));
// Expected output: "2012. 12. 20. 오전 3:00:00"

Синтаксис

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

Параметры

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

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

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

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

В реализациях без поддержки Intl.DateTimeFormat этот параметр игнорируется, и обычно используется локаль хоста.

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

Объект, настраивающий формат вывода. Соответствует параметру options конструктора Intl.DateTimeFormat(). Если weekday, year, month, day, dayPeriod, hour, minute, second и fractionalSecondDigits не определены, то year, month, day, hour, minute, second будут установлены в "numeric".

В реализациях без поддержки Intl.DateTimeFormat этот параметр игнорируется.

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

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

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

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

Примеры

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

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

const date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));

console.log(date.toLocaleString());
// "12/11/2012, 7:00:00 PM" if run in en-US locale with time zone America/Los_Angeles

Проверка поддержки параметров locales и options

Параметры locales и options могут поддерживаться не во всех реализациях, поскольку поддержка API интернационализации необязательна, и в некоторых системах может отсутствовать необходимая информация. Для реализаций без поддержки интернационализации toLocaleString() всегда использует системную локаль, что может быть не тем, что вам нужно. Поскольку любая реализация, поддерживающая параметры locales и options, должна поддерживать API Intl, вы можете проверить существование последнего для определения поддержки:

function toLocaleStringSupportsLocales() {
  return (
    typeof Intl === "object" &&
    !!Intl &&
    typeof Intl.DateTimeFormat === "function"
  );
}

Использование локалей

Этот пример показывает некоторые вариации локализованных форматов даты и времени. Чтобы получить формат языка, используемого в пользовательском интерфейсе вашего приложения, обязательно укажите этот язык (и, возможно, некоторые резервные языки) с помощью аргумента locales:

const date = new Date(Date.UTC(2012, 1, 2, 3, 0, 0));

// Formats below assume the local time zone of the locale;
// America/Los_Angeles for the US

// US English uses month-day-year order and 12-hour time with AM/PM
console.log(date.toLocaleString("en-US"));
// "2/1/2012, 7:00:00 PM" (UTC-8 is the previous day)

// British English uses day-month-year order and 24-hour time without AM/PM
console.log(date.toLocaleString("en-GB"));
// "02/02/2012, 03:00:00" (UTC+0 or UTC+1 depending on time of the year)

// Korean uses year-month-day order and 12-hour time with AM/PM
console.log(date.toLocaleString("ko-KR"));
// "2012. 2. 2. 오후 12:00:00"

// Arabic in most Arabic-speaking countries uses Eastern Arabic numerals
console.log(date.toLocaleString("ar-EG"));
// "٢‏/٢‏/٢٠١٢ ٥:٠٠:٠٠ ص"

// For Japanese, applications may want to use the Japanese calendar,
// where 2012 was the year 24 of the Heisei era
console.log(date.toLocaleString("ja-JP-u-ca-japanese"));
// "H24/2/2 12:00:00"

// When requesting a language that may not be supported, such as
// Balinese, include a fallback language (in this case, Indonesian)
console.log(date.toLocaleString(["ban", "id"]));
// "2/2/2012 11.00.00"

Использование параметров options

Результаты, предоставляемые toLocaleString(), можно настроить с помощью параметра options:

const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// Request a weekday along with a long date
const options = {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
};
console.log(date.toLocaleString("de-DE", options));
// Example output: "Donnerstag, 20. Dezember 2012"
// The exact date may shift depending on your local time zone.

// An application may want to use UTC and make that visible
options.timeZone = "UTC";
options.timeZoneName = "short";
console.log(date.toLocaleString("en-US", options));
// Example output: "Thursday, December 20, 2012 at UTC"

// Sometimes even the US needs 24-hour time
console.log(date.toLocaleString("en-US", { hour12: false }));
// Example output: "12/19/2012, 19:00:00"
// The exact date and time may shift depending on your local time zone.

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

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

Смотрите также

• Intl.DateTimeFormat
• Date.prototype.toLocaleDateString()
• Date.prototype.toLocaleTimeString()
• Date.prototype.toString()