BigInt.prototype.toLocaleString()

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

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

Попробуйте

const bigint = 123456789123456789n;

// German uses period for thousands
console.log(bigint.toLocaleString("de-DE"));
// Expected output: "123.456.789.123.456.789"

// Request a currency format
console.log(
  bigint.toLocaleString("de-DE", { style: "currency", currency: "EUR" }),
);
// Expected output: "123.456.789.123.456.789,00 €"

Синтаксис

toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)

Параметры

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

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

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

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

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

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

Объект, настраивающий вывод. Соответствует параметру options конструктора Intl.NumberFormat().

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

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

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

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

В реализациях с Intl.NumberFormat это эквивалентно new Intl.NumberFormat(locales, options).format(number).

Примеры

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

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

const bigint = 3500n;

console.log(bigint.toLocaleString());
// "3,500" if in U.S. English locale

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

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

function toLocaleStringSupportsLocales() {
  return (
    typeof Intl === "object" &&
    !!Intl &&
    typeof Intl.NumberFormat === "function"
  );
}

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

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

const bigint = 123456789123456789n;

// German uses period for thousands
console.log(bigint.toLocaleString("de-DE"));
// 123.456.789.123.456.789

// Arabic in most Arabic speaking countries uses Eastern Arabic digits
console.log(bigint.toLocaleString("ar-EG"));
// ١٢٣٬٤٥٦٬٧٨٩٬١٢٣٬٤٥٦٬٧٨٩

// India uses thousands/lakh/crore separators
console.log(bigint.toLocaleString("en-IN"));
// 1,23,45,67,89,12,34,56,789

// the nu extension key requests a numbering system, e.g. Chinese decimal
console.log(bigint.toLocaleString("zh-Hans-CN-u-nu-hanidec"));
// 一二三,四五六,七八九,一二三,四五六,七八九

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

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

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

const bigint = 123456789123456789n;

// request a currency format
console.log(
  bigint.toLocaleString("de-DE", { style: "currency", currency: "EUR" }),
);
// 123.456.789.123.456.789,00 €

// the Japanese yen doesn't use a minor unit
console.log(
  bigint.toLocaleString("ja-JP", { style: "currency", currency: "JPY" }),
);
// ￥123,456,789,123,456,789

// limit to three significant digits
console.log(bigint.toLocaleString("en-IN", { maximumSignificantDigits: 3 }));
// 1,23,00,00,00,00,00,00,000

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

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

См. также

• Intl.NumberFormat
• BigInt.prototype.toString()