Date.prototype.toLocaleDateString()
Метод toLocaleDateString()
(до рядка дати згідно з локаллю) примірників Date
повертає рядок із чутливим до мови відображенням тієї частини вказаної дати, яка містить лише календарну дату, в часовій зоні користувацького агента. В тих реалізаціях, що мають підтримку API Intl.DateTimeFormat
, цей метод просто викликає Intl.DateTimeFormat
.
Під час форматування великої кількості дат, краще створити окремий об'єкт Intl.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()
.
Повернене значення
Рядок, що позначає ту частку переданого примірника Date
, яка містить дату, сформований згідно із притаманними мові правилами.
В реалізаціях, що містять Intl.DateTimeFormat
, це еквівалентно викликові new Intl.DateTimeFormat(locales, options).format(date)
, де параметр options
нормалізовано так, як описано вище.
Приклади
Застосування toLocaleDateString()
В найпростішому випадку, без вказання конкретної локалі, буде повернено рядок, відформатований згідно з усталеними локаллю та опціями.
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 | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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 |