Date.prototype.toLocaleTimeString()

Сводка

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

Синтаксис

dateObj.toLocaleTimeString([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, однако, если все свойства hour, minute и second равны undefined, то их значения предполагаются равными "numeric".

Примеры

Пример: использование метода toLocaleTimeString()

При базовом использовании без указания локали возвращается строка, отформатированная в соответствии с локалью и опциями по умолчанию.

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

// Вывод toLocaleTimeString() без аргументов зависит от реализации,
// локали по умолчанию и часового пояса по умолчанию
console.log(date.toLocaleTimeString());
// → "7:00:00 PM", если код запущен с локалью en-US и часовым поясом America/Los_Angeles

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

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

function toLocaleTimeStringSupportsLocales() {
  try {
    new Date().toLocaleTimeString('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 для локали США

// В американском английском используется 12-часовой формат времени
console.log(date.toLocaleTimeString('en-US'));
// → "7:00:00 PM"

// В британском английском используется 24-часовой формат времени
console.log(date.toLocaleTimeString('en-GB'));
// → "03:00:00"

// В корейском используется 12-часовой формат времени
console.log(date.toLocaleTimeString('ko-KR'));
// → "오후 12:00:00"

// В большинстве арабоговорящих стран используют настоящие арабские цифры
console.log(date.toLocaleTimeString('ar-EG'));
// → "٧:٠٠:٠٠ م"

// Если запрашиваемый язык может не поддерживаться, например
// балийский, откатываемся на запасной язык, в данном случае индонезийский
console.log(date.toLocaleTimeString(['ban', 'id']));
// → "11.00.00"

Пример: использование аргумента options

Результат, предоставляемый методом toLocaleTimeString(), может быть настроен с помощью аргумента options:

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

// Приложение может захотеть использовать UTC и показать это
var options = { timeZone: 'UTC', timeZoneName: 'short' };
console.log(date.toLocaleTimeString('en-US', options));
// → "3:00:00 AM GMT"

// Иногда даже в США нужен 24-х часовой формат времени
console.log(date.toLocaleTimeString('en-US', { hour12: false }));
// → "19:00:00"

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

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

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

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

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

BCD tables only load in the browser

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