Date.prototype.toLocaleTimeString()

Интерактивный пример

// 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(). Опция timeStyle должна быть undefined или будет возникать TypeError. Если weekday, year, month и day одновременно равны undefined, то year, month и day будут установлены в "numeric".

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

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

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

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

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

Примеры

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

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

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 могут поддерживаться не во всех реализациях. В реализациях без поддержки интернационализации 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));

// Форматирование ниже предполагает, что местный часовой пояс равен
// 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:

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"

// Отображение только часов и минут, используем локаль по умолчанию (пусть массив)
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()