Date.prototype.toLocaleString()

Метод toLocaleString() (до рядка згідно з локаллю) примірників Date повертає рядок з чутливим до мови представленням дати в локальній часовій зоні. У реалізаціях з підтримкою 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, вимагається ігнорувати обидва параметри, що робить вжиту локаль та форму поверненого рядка цілковито залежною від реалізацій.

locales Необов'язкове

Рядок із позначенням мови у форматі BCP 47, або масив таких рядків. Відповідає параметрові locales конструктора Intl.DateTimeFormat().

В тих реалізаціях, що не мають підтримки Intl.DateTimeFormat, цей параметр ігнорується, і зазвичай використовується локаль хоста.

options Необов'язкове

Об'єкт, що підлаштовує формат виводу. Відповідає параметрові options конструктора Intl.DateTimeFormat(). Опція timeStyle повинна залишатися невизначеною — інакше викидатиметься виняток TypeError. Якщо невизначеними є всі опції: weekday, year, month, та day — то значеннями year, month, і day буде встановлено "numeric".

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

Докладніше про ці параметри та про те, як їх використовувати — в розділі Конструктор Intl.DateTimeFormat().

Повернене значення

Рядок, що позначає дату, сформований згідно із притаманними мові правилами.

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

Примітка: В більшості випадків форматування, повернене toLocaleString(), є сталим. Проте вивід може відрізнятися в різних реалізаціях, навіть із використанням однієї локалі: відмінності виводу є свідомими та дозволені специфікацією. Також вивід може бути не таким, як ви очікуєте. Наприклад, рядок може містити нерозривні пробіли або бути оточеним символами контролю напрямку письма. Не слід порівнювати результати toLocaleString() із жорстко зафіксованими сталими значеннями.

Приклади

Застосування toLocaleString()

В найпростішому випадку, без вказання значення locale, буде повернено рядок, відформатований згідно з усталеними локаллю та опціями.

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

// Без аргументів, toLocaleString() залежить від реалізації,
// усталеної локалі та усталеного часового поясу
console.log(date.toLocaleDateString());
// "12/11/2012, 7:00:00 PM", якщо виконано в локалі en-US та часовому поясі 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, 11, 20, 3, 0, 0));

// формати, наведені нижче, приймають часовий пояс за місцевий для локалі;
// America/Los_Angeles для US

// Американська англійська послуговується послідовністю місяць-день-рік і 12-годинним часом, із AM чи PM
console.log(date.toLocaleString("en-US"));
// "12/19/2012, 7:00:00 PM"

// В британській англійській вживають послідовність день-місяць-рік і 24 годинним часом, без AM чи PM
console.log(date.toLocaleString("en-GB"));
// "20/12/2012 03:00:00"

// Корея використовує порядок рік-місяць-день і 12-годинний час, із AM чи PM
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"

Застосування опцій

Результат, наданий методом toLocaleString(), можна налаштувати за допомогою параметра options:

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

// Запитати день тижня разом із довгим форматом дати
const 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"

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

Сумісність із браузерами

Дивіться також

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