Date.prototype.toLocaleString()

Метод toLocaleString() повертає рядкове представлення дати згідно налаштувань мови.

Нові аргументи locales та options дозволяють застосункам вказувати мову, чиї правила форматування мають застосовуватись та налаштовувати поведінку функції.

У старших реалізаціях, які ігнорують аргументи locales та options, мовні налаштування та форма поверненого рядка повністю залежать від реалізації.

Синтаксис

dateObj.toLocaleString([locales[, options]])

Параметри

Аргументи locales та options налаштовують поведінку функції та дозволяють застосункам вказувати мову, чиї правила форматування мають застосовуватись. У тих реалізаціях, які ігнорують аргументи locales та options, мовні налаштування та форма поверненого рядка повністю залежать від реалізації.

Дивіться конструктор Intl.DateTimeFormat(), щоб дізнатись подробиці щодо цих параметрів та їхнього використання.

Значенням за замовчуванням для кожної властивості компонента дати-часу є undefined. Але, якщо властивості weekday, year, month, day усі дорівнюють undefined, тоді year, month, та day вважаються числовими значеннями.

Повертає

Рядкове представлення наданої дати згідно правил встановленої мови.

Швидкодія

При форматуванні великої кількості дат краще створити об'єкт Intl.DateTimeFormat (en-US) та використовувати функцію, надану його властивістю format (en-US).

Приклади

Використання toLocaleString()

При загальному використанні, без зазначення мови, повертається рядок у мовному форматі, що стоїть за замовчуванням, та з початковими параметрами.

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

// toLocaleString() без аргументів залежить від реалізації,
// мова та часовий пояс за замовчуванням
console.log(date.toLocaleString());
// → "12/11/2012, 7:00:00 PM" при використанні мови en-US з часовим поясом America/Los_Angeles

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

Аргументи locales та options ще не підтримуються в усіх переглядачах. Для перевірки їхньої підтримки у реалізації можна скористатись вимогою, згідно якої недозволені мовні позначення відхиляються з винятком RangeError:

function toLocaleStringSupportsLocales() {
  try {
    new Date().toLocaleString('i');
  } catch (e) {
    return e instanceof RangeError;
  }
  return false;
}

Використання locales

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

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

// наведені приклади припускають використання локального часового поясу для мови;
// для US це America/Los_Angeles

// американська англійська використовує порядок місяць-день-рік та 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"

Використання options

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

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

// вивести день тижня разом з довгою датою
let 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"

Уникайте порівнювати відформатовану дату зі статичними значеннями

Як правило, відформатовані значення, що повертає метод toLocaleString(), сумісні між собою. Однак, це може змінитись у майбутньому, і не гарантовано для усіх мов; варіації у форматах виводу визначаються дизайном та дозволені специфікацією.

З найбільш помітного, переглядачі IE та Edge вставляють двонаправлені керівні символи навколо дат, щоб виведений текст правильно поєднувався з іншим текстом.

З цієї причини ви не можете гарантовано порівняти результати toLocaleString() зі статичним значенням:

"1/1/2019, 01:00:00" === new Date("2019-01-01T01:00:00Z").toLocaleString("en-US");
// true у Firefox та інших
// false у IE та Edge

Заувага: Більше подробиць та прикладів дивіться у цьому обговоренні на StackOverflow.

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

Специфікація
ECMAScript (ECMA-262)
The definition of 'Date.prototype.toLocaleString' in that specification.
ECMAScript Internationalization API (ECMA-402)
The definition of 'Date.prototype.toLocaleString' in that specification.

Сумісність з веб-переглядачами

BCD tables only load in the browser

Див. також