--- title: Date.prototype.toLocaleString() slug: Web/JavaScript/Reference/Global_Objects/Date/toLocaleString tags: - Date - JavaScript - Інтернаціоналізація - Довідка - метод translation_of: Web/JavaScript/Reference/Global_Objects/Date/toLocaleString ---
{{JSRef}}

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

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

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

{{EmbedInteractiveExample("pages/js/date-tolocalestring.html")}}

Синтаксис

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

Параметри

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

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

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

Повертає

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

Швидкодія

При форматуванні великої кількості дат краще створити об'єкт {{jsxref("Global_Objects/DateTimeFormat", "Intl.DateTimeFormat")}} та використовувати функцію, надану його властивістю {{jsxref("DateTimeFormat.prototype.format", "format")}}.

Приклади

Використання 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 ще не підтримуються в усіх переглядачах. Для перевірки їхньої підтримки у реалізації можна скористатись вимогою, згідно якої недозволені мовні позначення відхиляються з винятком {{jsxref("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.

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

Специфікація
{{SpecName('ESDraft', '#sec-date.prototype.tolocalestring', 'Date.prototype.toLocaleString')}}
{{SpecName('ES Int Draft', '#sup-date.prototype.tolocalestring', 'Date.prototype.toLocaleString')}}

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

{{Compat("javascript.builtins.Date.toLocaleString")}}

Див. також