Date.prototype.toLocaleTimeString()

Метод toLocaleTimeString() экземпляров Date возвращает строку с представлением времени этой даты в местном часовом поясе, чувствительным к языку. В реализациях с поддержкой Intl.DateTimeFormat API этот метод делегирует вызов Intl.DateTimeFormat.

Каждый раз, когда вызывается toLocaleTimeString, приходится выполнять поиск в большой базе данных строк локализации, что потенциально неэффективно. Когда метод вызывается много раз с одинаковыми аргументами, лучше создать объект Intl.DateTimeFormat и использовать его метод format(), так как объект DateTimeFormat запоминает переданные ему аргументы и может принять решение кэшировать часть базы данных, чтобы будущие вызовы format могли выполнять поиск строк локализации в более ограниченном контексте.

Попробуйте

// Depending on timezone, your results will vary
const event = new Date("August 19, 1975 23:15:30 GMT+00:00");

console.log(event.toLocaleTimeString("en-US"));
// Expected output: "1:15:30 AM"

console.log(event.toLocaleTimeString("it-IT"));
// Expected output: "01:15:30"

console.log(event.toLocaleTimeString("ar-EG"));
// Expected output: "١٢:١٥:٣٠ ص"

Синтаксис

toLocaleTimeString()
toLocaleTimeString(locales)
toLocaleTimeString(locales, options)

Параметры

Параметры locales и options настраивают поведение функции и позволяют приложениям указывать язык, соглашения которого следует использовать для форматирования.

В реализациях, поддерживающих Intl.DateTimeFormat API, эти параметры точно соответствуют параметрам конструктора Intl.DateTimeFormat(). Реализации без поддержки Intl.DateTimeFormat должны игнорировать оба параметра, делая используемую локаль и форму возвращаемой строки полностью зависимыми от реализации.

locales Необязательный

Строка с языковым тегом BCP 47 или массив таких строк. Соответствует параметру locales конструктора Intl.DateTimeFormat().

В реализациях без поддержки Intl.DateTimeFormat этот параметр игнорируется, и обычно используется локаль хоста.

options Необязательный

Объект, настраивающий формат вывода. Соответствует параметру options конструктора Intl.DateTimeFormat(). Если dayPeriod, hour, minute, second и fractionalSecondDigits имеют значение undefined, то hour, minute, second будут установлены в "numeric".

В реализациях без поддержки Intl.DateTimeFormat этот параметр игнорируется.

Подробнее об этих параметрах и способах их использования см. в конструкторе Intl.DateTimeFormat().

Возвращаемое значение

Строка, представляющая временную часть заданной даты в соответствии с языковыми соглашениями.

В реализациях с Intl.DateTimeFormat это эквивалентно new Intl.DateTimeFormat(locales, options).format(date), где options была нормализована, как описано выше.

Примеры

Использование toLocaleTimeString()

Базовое использование этого метода без указания locale возвращает отформатированную строку в локали по умолчанию и с параметрами по умолчанию.

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

// toLocaleTimeString() without arguments depends on the implementation,
// the default locale, and the default time zone
console.log(date.toLocaleTimeString());
// "7:00:00 PM" if run in en-US locale with time zone America/Los_Angeles

Проверка поддержки параметров locales и options

Параметры locales и options могут поддерживаться не во всех реализациях, поскольку поддержка API интернационализации является необязательной, и некоторые системы могут не иметь необходимых данных. Для реализаций без поддержки интернационализации toLocaleTimeString() всегда использует локаль системы, что может быть не тем, что вам нужно. Поскольку любая реализация, поддерживающая параметры locales и options, должна поддерживать Intl API, вы можете проверить наличие последнего для определения поддержки:

function toLocaleTimeStringSupportsLocales() {
  return (
    typeof Intl === "object" &&
    !!Intl &&
    typeof Intl.DateTimeFormat === "function"
  );
}

Использование locales

Этот пример показывает некоторые вариации локализованных форматов времени. Чтобы получить формат языка, используемого в пользовательском интерфейсе вашего приложения, убедитесь, что вы указали этот язык (и, возможно, некоторые резервные языки), используя аргумент locales:

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

// formats below assume the local time zone of the locale;
// America/Los_Angeles for the US

// US English uses 12-hour time with AM/PM
console.log(date.toLocaleTimeString("en-US"));
// "7:00:00 PM"

// British English uses 24-hour time without AM/PM
console.log(date.toLocaleTimeString("en-GB"));
// "03:00:00"

// Korean uses 12-hour time with AM/PM
console.log(date.toLocaleTimeString("ko-KR"));
// "오후 12:00:00"

// Arabic in most Arabic speaking countries uses real Arabic digits
console.log(date.toLocaleTimeString("ar-EG"));
// "٧:٠٠:٠٠ م"

// when requesting a language that may not be supported, such as
// Balinese, include a fallback language, in this case Indonesian
console.log(date.toLocaleTimeString(["ban", "id"]));
// "11.00.00"

Использование options

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

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

// An application may want to use UTC and make that visible
const options = { timeZone: "UTC", timeZoneName: "short" };
console.log(date.toLocaleTimeString("en-US", options));
// "3:00:00 AM GMT"

// Sometimes even the US needs 24-hour time
console.log(date.toLocaleTimeString("en-US", { hour12: false }));
// "19:00:00"

// Show only hours and minutes, use options with the default locale - use an empty array
console.log(
  date.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }),
);
// "20:01"

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

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

См. также

• Intl.DateTimeFormat
• Date.prototype.toLocaleDateString()
• Date.prototype.toLocaleString()
• Date.prototype.toTimeString()
• Date.prototype.toString()