Date.prototype.toLocaleTimeString()
Сводка
Метод toLocaleTimeString()
возвращает строку с языкозависимым представлением части со временем в этой дате. Новые аргументы locales
и options
позволяют приложениям определять язык, чьи соглашения по форматированию должны использоваться, а также менять поведение этого метода. В старых реализациях, игнорирующих аргументы locales
и options
, используемая локаль и форма возвращённой строки целиком зависит от реализации.
Синтаксис
dateObj.toLocaleTimeString([locales[, options]])
Параметры
Проверьте раздел Совместимость с браузерами, чтобы увидеть, какие браузеры поддерживают аргументы locales
и options
, и Пример: проверка поддержки аргументов locales
и options
для определения этой возможности.
Значением по умолчанию для каждой компоненты даты-времени является undefined
, однако, если все свойства hour
, minute
и second
равны undefined
, то их значения предполагаются равными "numeric"
.
Примеры
Пример: использование метода toLocaleTimeString()
При базовом использовании без указания локали возвращается строка, отформатированная в соответствии с локалью и опциями по умолчанию.
js
const 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
:
js
function toLocaleTimeStringSupportsLocales() {
try {
new Date().toLocaleTimeString("i");
} catch (e) {
return e.name === "RangeError";
}
return false;
}
Пример: использование аргумента locales
Этот пример показывает некоторые локализованные форматы времени. Для получения формата языка, используемого в пользовательском интерфейсе вашего приложения, убедитесь, что вы указали этот язык (и, возможно, несколько запасных языков) через аргумент locales
:
js
const 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
:
js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
// Приложение может захотеть использовать UTC и показать это
const 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