Number.prototype.toLocaleString()

Метод toLocaleString() повертає рядок, що відображає число у відповідності до налаштувань мови.

Синтаксис

numObj.toLocaleString([locales [, options]])

Параметри

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

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

Значення, що повертається

Рядок, що відображає число у відповідності до налаштувань мови.

Швидкодія

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

Приклади

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

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

var number = 3500;

console.log(number.toLocaleString()); // Відображає "3,500" у форматі U.S. English

Перевірка підтримки аргументів locales та options

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

function toLocaleStringSupportsLocales() {
  var number = 0;
  try {
    number.toLocaleString('i');
  } catch (e) {
    return e.name === 'RangeError';
  }
  return false;
}

До ES5.1, реалізації не були зобов'язані викидати виняток з помилкою діапазону, якщо toLocaleString викликався з аргументами.

Перевірка, яка працює в усіх хостах, в тому числі тих, що підтримують ECMA-262 до версії 5.1, полягає в безпосередньому тестуванні функцій, визначених у ECMA-402 як такі, що зобов'язані підтримувати регіональні налаштування для Number.prototype.toLocaleString:

function toLocaleStringSupportsOptions() {
  return !!(typeof Intl == 'object' && Intl && typeof Intl.NumberFormat == 'function');
}

Цей код перевіряє наявність глобального об'єкта Intl, перевіряє, що він не дорівнює null та що він має властивість NumberFormat, яка є функцією.

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

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

var number = 123456.789;

// В німецькій десятковим роздільником є кома, а крапка розділяє тисячі
console.log(number.toLocaleString('de-DE'));
// → 123.456,789

// Арабська у більшості арабськомовних країн використовує Індо-арабські цифри
console.log(number.toLocaleString('ar-EG'));
// → ١٢٣٤٥٦٫٧٨٩

// Індія використовує роздільники тисячі/лакх/крор
console.log(number.toLocaleString('en-IN'));
// → 1,23,456.789

// ключ розширення nu налаштовує систему нумерації, наприклад, китайську десяткову
console.log(number.toLocaleString('zh-Hans-CN-u-nu-hanidec'));
// → 一二三,四五六.七八九

// при запиті мови, яка, можливо, не підтримується, наприклад,
// балійської, додайте запасні мови, в даному випадку це індонезійська
console.log(number.toLocaleString(['ban', 'id']));
// → 123.456,789

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

Результат методу toLocaleString можна налаштувати за допомогою аргументу options:

var number = 123456.789;

// налаштування формату валюти
console.log(number.toLocaleString('de-DE', { style: 'currency', currency: 'EUR' }));
// → 123.456,79 €

// японська єна не використовує дробові розряди
console.log(number.toLocaleString('ja-JP', { style: 'currency', currency: 'JPY' }))
// → ¥123,457

// обмежити трьома значущими цифрами
console.log(number.toLocaleString('en-IN', { maximumSignificantDigits: 3 }));
// → 1,23,000

// Використовувати мову системи з параметрами для форматування чисел
var num = 30000.65;
console.log(num.toLocaleString(undefined, {minimumFractionDigits: 2, maximumFractionDigits: 2}));
// → "30,000.65" де мова системи англійська, або
// → "30.000,65" де мова системи німецька, або
// → "30 000,65" де мова системи французька

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

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

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

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
toLocaleStringChrome Full support 1Edge Full support 12
Notes
Full support 12
Notes
Notes Before Edge 18, numbers are rounded to 15 decimal digits. For example, (1000000000000005).toLocaleString('en-US') returns "1,000,000,000,000,010".
Firefox Full support 1IE Full support 5
Notes
Full support 5
Notes
Notes In Internet Explorer 11, numbers are rounded to 15 decimal digits. For example, (1000000000000005).toLocaleString('en-US') returns "1,000,000,000,000,010".
Opera Full support 4Safari 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
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 26Firefox 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 26Firefox 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
See implementation notes.
See implementation notes.

Див. також