Date.prototype.toLocaleTimeString()

Сводка

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

Синтаксис

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

Параметры

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

{{page('/ru/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat', 'Parameters')}}

Значением по умолчанию для каждой компоненты даты-времени является 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

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