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
.
Спецификации
Specification |
---|
ECMAScript Language Specification # sec-date.prototype.tolocaledatestring |
ECMAScript Internationalization API Specification # sup-date.prototype.tolocaledatestring |
Совместимость с браузерами
BCD tables only load in the browser