Number.prototype.toLocaleString()
Baseline
Widely available
This feature is well established and works across many devices and browser versions. Itâs been available across browsers since julho de 2015.
O método toLocaleString() retorna uma string com uma representação sensÃvel a linguagem deste número.
Os novos argumentos locales e options permitem às aplicações especificar a linguagem cujas convenções de formatações serão utilizadas e personalizar o comportamento da função. Nas implementações anteriores, que ignorava os argumentos locales e options arguments, a localização utilizada e a forma de retornar a string erão totalmente dependente da implementação.
Sintaxe
numObj.toLocaleString([locales [, options]])
Parâmetros
Dê uma olhada na seção Compatibilidade do Navegador para verificar quais navegadores suportam os argumentos locales e options, e o Exemplo: Verificando o suporte dos argumentos locales e options para detecção desta caracterÃstica.
Nota:
ECMAScript Internationalization API, implementada com o Firefox 29, incluiu o argumento locales ao método Number.toLocaleString(). Se o argumento for undefined, este método retorna os dÃgitos de localização especificados pelo SO, enquanto que as versões anteriores doFirefox retornavam os dÃgitos Ãrabe Ocidental. Esta mudança foi relatada como uma regressão que afeta a retrocompatibilidade que será corrigida em breve. (Erro do Firefox 999003)
Exemplos
Usando toLocaleString
No uso básico sem a especificação de uma localização, o método retornará uma string formatada com a localização e as opções padrão.
var numero = 3500;
console.log(numero.toLocaleString()); // Mostra "3,500" se a localização for U.S. English
Verificando o suporte dos argumentos locales e options
Os argumentos locales e options não são suportados por todos os navegadores ainda. Para verificar pelo suporte das implementações do ES5.1 e posteriores, a requisição de tags de linguagem ilegais são rejeitadas com uma exceção RangeError pode ser usada da seguinte forma:
function toLocaleStringSupportsLocales() {
var numero = 0;
try {
numero.toLocaleString("i");
} catch (e) {
return e.name === "RangeError";
}
return false;
}
Antes da ES5.1, implementações que não exigiam um tratamento de erro se toLocaleString fosse chamada com argumentos.
Uma verificação que funciona em todos os casos, incluindo aqueles que suportam ECMA-262 antes da edição 5.1, é testar pelas especificações de caracterÃsticadas da ECMA-402 que exigem suporte de opções regionais para Number.prototype.toLocaleString diretamente:
function toLocaleStringSupportsOptions() {
return !!(
typeof Intl == "object" &&
Intl &&
typeof Intl.NumberFormat == "function"
);
}
Estes testes para um objeto Intl global, verifica se ele não é null e se uma propriedade NumberFormat é uma função.
Usando locales
Este exemplo mostra algumas variações de formatos de números localizados. A fim de obter o formato da linguagem utilizada na interface do usuário da sua aplicação, tenha certeza de especificar a lÃngua (e possivelmente algumas lÃnguas reservas) usando o argumento locales:
var numero = 123456.789;
// O alemão usa vÃrgula como separador de decimal e ponto para milhares
console.log(numero.toLocaleString("de-DE"));
// â 123.456,789
// O árabe usa dÃgitos Ãrabes Orientais em muitos paÃses que falam árabe
console.log(numero.toLocaleString("ar-EG"));
// â ١٢٣٤٥٦٫٧٨٩
// A Ãndia usa separadores de milhares/cem mil/dez milhões
console.log(numero.toLocaleString("en-IN"));
// â 1,23,456.789
// A chave de extensão nu requer um sistema de numeração, ex. decimal chinês
console.log(numero.toLocaleString("zh-Hans-CN-u-nu-hanidec"));
// â ä¸äºä¸,åäºå
.ä¸å
«ä¹
// Quando informada uma lÃngua sem suporte, como balinês,
// inclua uma lÃngua reseva, neste caso indonésio
console.log(numero.toLocaleString(["ban", "id"]));
// â 123.456,789
Usando options
Os resultados obtidos por toLocaleString pode ser personalizado usando o argumento options:
var numero = 123456.789;
// informando um formato de moeda
console.log(
numero.toLocaleString("de-DE", { style: "currency", currency: "EUR" }),
);
// â 123.456,79 â¬
// o yen japonês não tem uma unidade menor
console.log(
numero.toLocaleString("ja-JP", { style: "currency", currency: "JPY" }),
);
// â ï¿¥123,457
// limitando a três dÃgitos significativos
console.log(numero.toLocaleString("en-IN", { maximumSignificantDigits: 3 }));
// â 1,23,000
Desempenho
Quando formatar uma grande quantidade de números, é melhor criar um objeto NumberFormat e usar a função fornecida pela propriedade NumberFormat.format.
Especificações
| Specification |
|---|
| ECMAScript® 2027 Language Specification # sec-number.prototype.tolocalestring |
| ECMAScript® 2027 Internationalization API Specification # sup-number.prototype.tolocalestring |