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() виводить і дату, і час. Це важливо враховувати при виборі правильного методу для ваших потреб.

Синтаксис

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

Параметри

locales

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

Значення:

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

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

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 цей параметр ігнорується.

Return

string

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

Переглядачі

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

Приклади

• Приклад 1
• Приклад 2
• Приклад 3

// Створюємо новий об’єкт 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 р."