Date.prototype.toLocaleTimeString()
===================================

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

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

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

Синтаксис
---------


```js
toLocaleTimeString()
toLocaleTimeString(locales)
toLocaleTimeString(locales, options)
```

### Параметры

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

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

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

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

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

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

Объект определяющий выходной формат. Соответствует параметру `options` (en-US) конструктора `Intl.DateTimeFormat()`. Опция `timeStyle` должна быть `undefined` или будет возникать `TypeError`. Если `weekday`, `year`, `month` и `day` одновременно равны `undefined`, то `year`, `month` и `day` будут установлены в `"numeric"`.

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

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

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

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

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

**Примечание:** В большинстве случаев форматирование, возвращаемое `toLocaleString()`, единообразно. Однако результат может быть разным в зависимости от времени, языка и реализации — это допускается спецификацией. Не следует сравнивать результат `toLocaleTimeString()` со статическими значениями.

Примеры
-------

### Использование `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` могут поддерживаться не во всех реализациях. В реализациях без поддержки интернационализации `toLocaleTimeString()` всегда использует системную локаль, что может оказаться не тем, что вам нужно. Поскольку любая реализация, поддерживающая параметры `locales` и `options`, должна поддерживать `Intl` API, проверить наличие последней можно таким способом:


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

### Использование параметра `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"

// Отображение только часов и минут, используем локаль по умолчанию (пусть массив)
console.log(
  date.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }),
);
// "20:01"
```

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

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.tolocaletimestring |
| ECMAScript Internationalization API Specification # sup-date.prototype.tolocaletimestring |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

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

* `Intl.DateTimeFormat`
* `Date.prototype.toLocaleDateString()`
* `Date.prototype.toLocaleString()`
* `Date.prototype.toTimeString()`
* `Date.prototype.toString()`