Date.prototype.toLocaleDateString()

Сводка

Метод toLocaleDateString() возвращает строку с языко-зависимым представлением части с датой в этой дате. Новые аргументы locales и options позволяют приложениям определять язык, чьи соглашения по форматированию должны использоваться, а также менять поведение этого метода. В старых реализациях, игнорирующих аргументы locales и options, используемая локаль и форма возвращённой строки целиком зависит от реализации.

Синтаксис

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

Параметры

Проверьте раздел Совместимость с браузерами, чтобы увидеть, какие браузеры поддерживают аргументы locales и options, и Пример: проверка поддержки аргументов locales и options для определения этой возможности.

locales

Необязательный параметр. Строка с языковой меткой BCP 47, либо массив таких строк. Описание общей формы и интерпретации аргумента locales смотрите на странице, посвящённой объекту Intl. Разрешены следующие ключи расширения Unicode:

nu
Используемая система нумерации. Возможные значения включают в себя: "arab", "arabext", "bali", "beng", "deva", "fullwide", "gujr", "guru", "hanidec", "khmr", "knda", "laoo", "latn", "limb", "mlym", "mong", "mymr", "orya", "tamldec", "telu", "thai", "tibt".
ca
Используемый календарь. Возможные значения включают в себя: "buddhist", "chinese", "coptic", "ethioaa", "ethiopic", "gregory", "hebrew", "indian", "islamic", "islamicc", "iso8601", "japanese", "persian", "roc".
options

Необязательный параметр. Объект с некоторыми или всеми из следующих свойств:

localeMatcher
Используемый алгоритм сопоставления локалей. Возможными значениями являются "lookup" и "best fit"; значением по умолчанию является "best fit". Информацию по этой опции смотрите на странице, посвящённой объекту Intl.
timeZone
Используемый часовой пояс. Единственным значением, которые реализации обязаны распознавать, является "UTC"; значением по умолчанию является часовой пояс по умолчанию среды выполнения. Реализации также могут распознавать названия часовых поясов из базы даных часовых поясов IANA, например "Asia/Shanghai", "Asia/Kolkata" или "America/New_York".
hour12
Определяет, использовать ли 12-ти часовой формат времени (в противовес 24-х часовому). Возможными значениями являются true и false; значение по умолчанию зависит от локали.
formatMatcher
Используемый алгоритм сопоставления форматов. Возможными значениями являются "basic" и "best fit"; значением по умолчанию является "best fit". Смотрите следующий абзац, объясняющий, как использовать это свойство.

Следующие свойства описывают компоненты даты/времени, используемые в форматированном выводе, и их желаемые представления. Реализации должны поддерживать, как минимум, следующие подмножества:

  • weekday, year, month, day, hour, minute, second
  • weekday, year, month, day
  • year, month, day
  • year, month
  • month, day
  • hour, minute, second
  • hour, minute

Также реализации могут поддерживать другие подмножества и запросы будут сравниваться со всеми доступными подмножествами представлений для поиска наилучшего соответствия. Для такого сравнения доступно два алгоритма, нужный из которых выбирается свойством formatMatcher: чётко определённый алгоритм "basic" и зависящий от реализации алгоритм "best fit".

weekday
Представление дней недели. Возможными значениями являются "narrow", "short" и "long".
era
Представление эр. Возможными значениями являются "narrow", "short" и "long".
year
Представление лет. Возможными значениями являются "numeric" и "2-digit".
month
Представление месяцев. Возможными значениями являются "numeric", "2-digit", "narrow", "short" и "long".
day
Представление дней. Возможными значениями являются "numeric" и "2-digit".
hour
Представление часов. Возможными значениями являются "numeric" и "2-digit".
minute
Представление минут. Возможными значениями являются "numeric" и "2-digit".
second
Представление секунд. Возможными значениями являются "numeric" и "2-digit".
timeZoneName
Представление названий часовых поясов. Возможными значениями являются "short" и "long".

Значением по умолчанию для каждой компоненты даты-времени является undefined, однако, если все свойства weekday, year, month и day равны undefined, то их значения предполагаются равными "numeric".

Примеры

Пример: использование метода 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));

// Форматирование ниже предполагает, что местный часовой пояс равен
// 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('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"

Производительность

При форматировании большого количества дат лучшим вариантом будет создание объекта Intl.DateTimeFormat и использование функции, предоставляемой его свойством format.

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

Спецификация Статус Комментарии
ECMAScript 3-е издание. Стандарт Изначальное определение. Реализована в JavaScript 1.0.
ECMAScript 5.1 (ECMA-262)
Определение 'Date.prototype.toLocaleDateString' в этой спецификации.
Стандарт  
ECMAScript 6 (ECMA-262)
Определение 'Date.prototype.toLocaleDateString' в этой спецификации.
Кандидат в рекомендации  
ECMAScript Internationalization API 1.0 (ECMA-402)
Определение 'Date.prototype.toLocaleDateString' в этой спецификации.
Стандарт Определяет аргументы locales и options.

Совместимость с браузерами

Возможность Chrome Firefox (Gecko) Internet Explorer Opera Safari
Базовая поддержка (Да) (Да) (Да) (Да) (Да)
Аргументы locales и options 24 + поддержка временных зон, отличных от UTC 29 (29) 11 15 Нет
Возможность Android Chrome для Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Базовая поддержка (Да) (Да) (Да) (Да) (Да) (Да)
Аргументы locales и options Нет 26 Нет
ошибка 864843
Нет Нет Нет

Смотрите также

Метки документа и участники

 Внесли вклад в эту страницу: Mingun, teoli, kup
 Обновлялась последний раз: Mingun,