Date.prototype.toLocaleDateString()

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

Синтаксис

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

Параметри

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

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

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

Повертає

Рядкове відображення елементів дати наданого екземпляра Date у відповідності до налаштувань мови.

Швидкодія

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

Приклади

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

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

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

function toLocaleDateStringSupportsLocales() {
  try {
    new Date().toLocaleDateString('i');
  } catch (e) {
    return e.name === 'RangeError';
  }
  return false;
}

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

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

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

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

// В американській англійській використовується порядок місяць-день-рік
console.log(date.toLocaleDateString('en-US'));
// → "12/19/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"

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

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

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

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

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

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

BCD tables only load in the browser

Див. також