JS метод Date.toLocaleString()

Загальний опис

Date.prototype.toLocaleString() перетворює дати та час до формату рядка, який відповідає локальним налаштуванням конкретної культурної локації (або локалі) користувача. Це часто корисно при створенні міжнародних застосунків або веб-сайтів, які слід адаптувати до відвідувачів з різних регіонів світу.

Один із основних сценаріїв використання цього методу – це адаптація дат та часу до місцевого формату. Наприклад, дата "20.12.2022" у деяких країнах може бути представлена як "12/20/2022" або навіть як "2022/12/20". Якщо розробник хоче вивести дату так, щоб вона виглядала зрозуміло для користувача згідно з його регіональними налаштуваннями, Date.prototype.toLocaleString() стане незамінним інструментом. Розглянемо практичний приклад:

let date = new Date();
console.log(date.toLocaleString());  // Вивід може бути "12/20/2022, 10:15:30 AM" або іншим, в залежності від локації користувача.

Додатково, цей метод приймає два параметри: locales та options, які дозволяють керувати деталями форматування. locales може бути рядком з тегом мови BCP 47 або масивом таких рядків, що дає можливість задати бажану локацію або декілька локацій у порядку пріоритету. options — це об'єкт, що містить додаткові налаштування форматування, такі як використання скорочених назв місяців, днів тижня тощо.

Так, використання параметра options може допомогти нам отримати лише дату без часу або навпаки:

let date = new Date();
let options = { year: 'numeric', month: 'long', day: 'numeric' };
console.log(date.toLocaleString('uk-UA', options));  // "20 грудня 2022 р."

Ще однією особливістю є підтримка Intl.DateTimeFormat конструктора. Це об’єкт конструктора в JavaScript, який дозволяє вам форматувати дату і час відповідно до мови і регіональних налаштувань користувача. Якщо середовище виконання не підтримує Intl.DateTimeFormat, параметри locales та options можуть бути проігноровані, і використовуватиметься локаль хоста.

Date.prototype.toLocaleString() відрізняється від інших методів, таких як toLocaleDateString() або toLocaleTimeString(). Ці методи виводять лише дату або час відповідно, тоді як toLocaleString() виводить і дату, і час. Це важливо враховувати при виборі правильного методу для ваших потреб.

правити

Порада

Досвідчені розробники можуть оптимізувати виконання, кешуючи об’єкти Intl.DateTimeFormat для повторного використання. Це зокрема корисно у великих застосунках, де Date.prototype.toLocaleString() викликається часто, і може сприяти підвищенню продуктивності застосунку.

автор: Bond правити

Порада

Для уникнення можливих проблем зі сумісністю, рекомендується тестувати роботу Date.prototype.toLocaleString() в різних браузерах і на різних платформах. Не у всіх веб-оточеннях поведінка цього методу може бути ідентичною, тому важливо переконатися, що він веде себе очікуваним чином у кожному конкретному середовищі.

автор: Bond правити

Нотатка

Початківцям слід пам’ятати, що при використанні методу $Date.prototype.toLocaleString()$, завжди перевіряйте, чи правильно він інтерпретує часові пояси і чи він враховує літній час. Це може бути критично, особливо при взаємодії з іншими датами та часовими мітками у вашому застосунку.

автор: Bond правити

Нотатка

Зважайте на необхідність виведення конкретних елементів дати та часу. Використовуючи Date.prototype.toLocaleString(), ви можете налаштувати виведення, використовуючи параметр options і вказуючи потрібні компоненти, наприклад, { year: 'numeric', month: 'long', day: 'numeric', hour: '2-digit', minute: '2-digit' }, щоб вивести потрібну інформацію в зручному форматі.

автор: Bond правити

+ додати пораду чи нотатку

Синтаксис

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

Параметри

locales

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

Значення:

• Рядок (наприклад, "en-US", "uk-UA").
• Масив рядків (наприклад, ["en-US", "fr-FR"]).

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

автор: Bond

правити

options

Об'єкт з різними властивостями для налаштування виводу, такими як:

• weekday: наприклад, "long", "short", "narrow".
• year: наприклад, "numeric", "2-digit".
• month: наприклад, "numeric", "2-digit", "long", "short", "narrow".
• day: наприклад, "numeric", "2-digit".
• hour, minute, second: наприклад, "numeric", "2-digit".
• fractionalSecondDigits: ціле число від 1 до 3.

Якщо weekday, year, month, day, dayPeriod, hour, minute, second, та fractionalSecondDigits не визначені, тоді year, month, day, hour, minute, second будуть встановлені як "numeric".

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

автор: Bond

правити

Повернення

string

Повертає рядок, який представляє задану дату відповідно до конвенцій конкретної мови (language-specific conventions). Тобто, цей метод конвертує дату та час у формат, зрозумілий для користувача, з урахуванням його локалі.

автор: Bond

правити

Переглядачі

Стаціонарні переглядачі Мобільні переглядачі Серверні переглядачі

Підтримка: стаціонарні переглядачі

Переглядач
	1	1	1	3	12

Підтримка: мобільні переглядачі

Переглядач
	4.4	18	4	1

Підтримка: серверні переглядачі

Переглядач
	0.10.0	1.0

Приклади

+ запропонувати свій приклад у пісочниці

// Створюємо новий об’єкт Date
let currentDate = new Date();

// Виводимо локалізовану строку дати та часу
let localizedString = currentDate.toLocaleString('uk-UA', {
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  hour: '2-digit',
  minute: '2-digit',
  second: '2-digit',
  timeZoneName: 'short'
});

console.log(localizedString); // Наприклад: "24 вересня 2023 р., 14:45:30 GMT+2"

// Створюємо об’єкт Date для 1 січня 2023 року
let newYearDate = new Date(2023, 0, 1);

// Виводимо локалізовану строку дати без часу
let dateString = newYearDate.toLocaleString('uk-UA', {
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  hour: undefined,
  minute: undefined,
  second: undefined,
});

console.log(dateString); // "1 січня 2023 р."