Date.prototype.toLocaleDateString()

Метод toLocaleDateString() (до рядка дати згідно з локаллю) примірників Date повертає рядок із чутливим до мови відображенням тієї частини поточної дати, яка містить лише календарну дату, в локальній часовій зоні. В тих реалізаціях, що мають підтримку API Intl.DateTimeFormat, цей метод просто викликає Intl.DateTimeFormat.

Щоразу, коли викликається toLocaleString, цей метод мусить виконати пошук у великій базі даних рядків локалізації, що потенційно може бути неефективним. Коли цей метод викликається багато разів з однаковими аргументами, краще створити об'єкт Intl.DateTimeFormat і використовувати його метод format(), оскільки об'єкт DateTimeFormat запам'ятовує передані йому аргументи, і може вирішити кешувати частину бази даних, щоб майбутні виклики format могли шукати рядки локалізації в більш обмеженому контексті.

Спробуйте його в дії

Синтаксис

toLocaleDateString()
toLocaleDateString(locales)
toLocaleDateString(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), де параметр options нормалізовано так, як описано вище.

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

Приклади

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

Базове використання цього методу без задання locale повертає відформатований рядок згідно з усталеною локаллю та з усталеними опціями.

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

// Без аргументів, toLocaleDateString() залежить від реалізації,
// усталеної локалі та усталеного часового поясу
console.log(date.toLocaleDateString());
// "12/11/2012", якщо виконано в локалі en-US та часовому поясі America/Los_Angeles

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

Параметри locales та options можуть підтримуватися не у всіх реалізаціях, оскільки підтримка API інтернаціоналізації є необов'язковою, і деякі системи можуть не мати необхідних даних. У реалізаціях без підтримки інтернаціоналізації toLocaleString() завжди використовує локаль системи, що може не відповідати вашим потребам. Оскільки будь-яка реалізація, що підтримує параметри locales та options, повинна підтримувати API Intl, ви можете перевірити його наявність для підтримки:

function toLocaleDateStringSupportsLocales() {
  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

// Американська англійська послуговується послідовністю місяць-день-рік
console.log(date.toLocaleDateString("en-US"));
// "12/20/2012"

// В британській англійській вживають послідовність день-місяць-рік
console.log(date.toLocaleDateString("en-GB"));
// "20/12/2012"

// Корея використовує порядок рік-місяць-день
console.log(date.toLocaleDateString("ko-KR"));
// "2012. 12. 20."

// В разі перської мови, доволі складно вручну привести дату до сонячної хіджрі
console.log(date.toLocaleDateString("fa-IR"));
// "۱۳۹۱/۹/۳۰"

// Араби в більшості арабомовних країн використовують справжні арабські цифри
console.log(date.toLocaleDateString("ar-EG"));
// "٢٠‏/١٢‏/٢٠١٢"

// для японської локалі, застосунки можуть вирішити використовувати такий японський
// календар, де 2012 рік був 24 роком епохи Хейсей
console.log(date.toLocaleDateString("ja-JP-u-ca-japanese"));
// "24/12/20"

// в разі запиту мови, яка може не підтримуватись, наприклад — балійської,
// варто додати запасну мову, в цьому випадку — індонезійську
console.log(date.toLocaleDateString(["ban", "id"]));
// "20/12/2012"

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

Результат, наданий методом toLocaleDateString(), можна налаштувати за допомогою параметра 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.toLocaleDateString("de-DE", options));
// "Donnerstag, 20. Dezember 2012"

// Якийсь застосунок може вирішити вжити часовий пояс UTC, і явно показати це
options.timeZone = "UTC";
options.timeZoneName = "short";
console.log(date.toLocaleDateString("en-US", options));
// "Thursday, December 20, 2012, UTC"

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

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

desktop mobile server
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on iOS Samsung Internet Deno Node.js
toLocaleDateString
Chrome Full support 1
Edge Full support 12
Firefox Full support 1
Internet Explorer Full support 5.5
Opera Full support 5
Safari Full support 1
WebView Android Full support 1
Chrome Android Full support 18
Firefox for Android Full support 4
Opera Android Full support 10.1
Safari on iOS Full support 1
Samsung Internet Full support 1.0
Deno Full support 1.0
Node.js Full support 0.10.0
IANA time zone names in timeZone option
Chrome Full support 24
Edge Full support 14
Firefox Full support 52
Internet Explorer No support No
Opera Full support 15
Safari Full support 7
WebView Android Full support 4.4
Chrome Android Full support 25
Firefox for Android Full support 56
Opera Android Full support 14
Safari on iOS Full support 7
Samsung Internet Full support 1.5
Deno Full support 1.8
Node.js Full support 0.12.0
locales
Chrome Full support 24
Edge Full support 12
Firefox Full support 29
Internet Explorer Full support 11
Opera Full support 15
Safari Full support 10
WebView Android Full support 4.4
Chrome Android Full support 25
Firefox for Android Full support 56
Opera Android Full support 14
Safari on iOS Full support 10
Samsung Internet Full support 1.5
Deno Full support 1.8
Node.js Full support 13.0.0
options
Chrome Full support 24
Edge Full support 12
Firefox Full support 29
Internet Explorer Full support 11
Opera Full support 15
Safari Full support 10
WebView Android Full support 4.4
Chrome Android Full support 25
Firefox for Android Full support 56
Opera Android Full support 14
Safari on iOS Full support 10
Samsung Internet Full support 1.5
Deno Full support 1.0
Node.js Full support 0.12.0

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