Date.prototype.toLocaleTimeString()

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

Синтаксис

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

Параметри

Аргументи locales та options налаштовують поведінку функції та дозволяють застосункам вказувати мову, чиї правила форматування мають застосовуватись. У тих реалізаціях, які ігнорують аргументи locales та options, мовні налаштування та форма поверненого рядка повністю залежать від реалізації.

Дивіться конструктор Intl.DateTimeFormat(), щоб дізнатись подробиці щодо цих параметрів та їхнього використання.

Значенням за замовчуванням для кожної властивості компонента дати-часу є undefined, але, якщо властивості hour, minute, second усі дорівнюють undefined, тоді hourminute та second вважаються числовими значеннями.

Повертає

Рядкове відображення елементів часу наданого екземпляра Date згідно правил встановленої мови.

Швидкодія

При форматуванні великої кількості дат краще створити об'єкт Intl.DateTimeFormat та використовувати функцію, надану його властивістю format.

Приклади

Використання toLocaleTimeString()

При загальному використанні, без зазначення мови, повертається рядок у мовному форматі, що стоїть за замовчуванням, та з початковими параметрами.

var 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:

function toLocaleTimeStringSupportsLocales() {
  try {
    new Date().toLocaleTimeString('i');
  } catch (e) {
    return e​.name === 'RangeError';
  }
  return false;
}

Використання locales

Цей приклад демонструє деякі варіації локалізованих форматів часу. Щоб отримати формат мови, задіяної в інтерфейсі вашого застосутку, переконайтесь, що вказали цю мову (та, можливо, кілька запасних мов) за допомогою аргументу locales:

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

// наведені приклади припускають використання локального часового поясу для мови;
// для US це America/Los_Angeles

// американська англійська використовує 12-годинний формат часу з AM/PM
console.log(date.toLocaleTimeString('en-US'));
// → "7:00:00 PM"

// британська англійська використовує 24-годинний часовий формат без AM/PM
console.log(date.toLocaleTimeString('en-GB'));
// → "03:00:00"

// корейська мова використовує 12-годинний часовий формат з AM/PM
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:

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

// застосунок може використати час UTC, так, щоб це було видно
var options = { timeZone: 'UTC', timeZoneName: 'short' };
console.log(date.toLocaleTimeString('en-US', options));
// → "3:00:00 AM UTC"

// іноді навіть американській англійській потрібен 24-годинний час
console.log(date.toLocaleTimeString('en-US', { hour12: false }));
// → "19:00:00"

// показати лише години та хвилини, використати options та мову за замовчуванням - передати порожній масив
console.log(date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }));
// → "20:01"

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

Специфікація
ECMAScript (ECMA-262)
The definition of 'Date.prototype.toLocaleTimeString' in that specification.
ECMAScript Internationalization API (ECMA-402)
The definition of 'Date.prototype.toLocaleTimeString' in that specification.

Сумісність з веб-переглядачами

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
toLocaleTimeStringChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 5.5Opera Full support 5Safari Full support 1WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 10.1Safari iOS Full support 1Samsung Internet Android Full support 1.0nodejs Full support 0.1.100
IANA time zone names in timeZone optionChrome Full support 24Edge Full support 14Firefox Full support 52IE No support NoOpera Full support 15Safari Full support 6.1WebView Android Full support 4.4Chrome Android Full support 25Firefox Android No support NoOpera Android Full support 14Safari iOS Full support 7Samsung Internet Android Full support 1.5nodejs Full support 0.12
localesChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android Full support 4.4Chrome Android Full support 25Firefox Android Full support 56Opera Android Full support 14Safari iOS Full support 10Samsung Internet Android Full support 1.5nodejs Full support 13.0.0
Full support 13.0.0
Partial support 0.12
Notes
Notes Before version 13.0.0, only the locale data for en-US is available by default. When other locales are specified, the function silently falls back to en-US. To make full ICU (locale) data available for versions prior to 13, see Node.js documentation on the --with-intl option and how to provide the data.
optionsChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android Full support 4.4Chrome Android Full support 25Firefox Android Full support 56Opera Android Full support 14Safari iOS Full support 10Samsung Internet Android Full support 1.5nodejs Full support 0.12

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

Див. також