O método Number.prototype.toLocaleString() permite formatar um número de acordo com a nacionalidade desejada. A partir de uma entrada do tipo number, ele devolve uma string com a formatação padrão ou a que foi definida através das opções disponíveis.
Conteúdo:
Números
Para o método Number.prototype.toLocaleString() são aceitos três estilos de formatação:
-
decimal(default): para números simples -
percent: para porcentagem -
currency: para valores monetários
Estilo decimal
É o valor padrão e está definido de forma implícita.
Separadores de milhar
Podemos definir os separadores de milhar de acordo com a localidade do ambiente atual de hospedagem:
const brazilPopulation = 213317639;
brazilPopulation.toLocaleString();
// Output: "213.317.639"
Mas, se quisermos especificar de qual país queremos a formatação, basta passar uma string com a tag da linguagem de acordo com a BCP 47 para qual desejamos formatar.
Geralmente, essa tag é composta de uma ou mais subtags, sendo a primeira da linguagem principal e a segunda com o código do país, de acordo com a ISO 3166-1 alpha-2. Exemplo: pt-BR ou en-us.
const brazilPopulation = 213317639;
brazilPopulation.toLocaleString('ja-JP');
// Output: "213,317,639"
Desabilitando separadores de milhar
Também podemos definir se queremos ou não usar separadores de milhares, definindo um valor booleano para a propriedade useGrouping, o valor default é true
const brazilPopulation = 213317639;
brazilPopulation.toLocaleString('pt-BR', {useGrouping: false})
// Output "213317639"
Inteiros e Dígitos Fracionados (Casas Decimais):
O estilo padrão para formatação de Number.prototype.toLocaleString() é decimal, porém podemos definir algumas opções:
minimumIntegerDigits:
- Define a quantidade mínima de dígitos inteiros
- Intervalo de Valores: 1 ~ 21
- Valor Default: 1
const number = 10.175;
number.toLocaleString('pt-br', {style: 'decimal', minimumIntegerDigits: 5});
// Output: "00.010,175"
Repare que ele adiciona a quantidade de zeros à esquerda necessárias para compensar os dígitos faltantes.
minimumFractionDigits:
- Define a quantidade mínima de dígitos fracionados
- Intervalo de Valores: 1 ~ 20
- Valor Default: 0
const number = 10.175;
number.toLocaleString('pt-br', {style: 'decimal', minimumFractionDigits: 10});
// Output: "10,17500000"
Semelhante a minimumIntegerDigits, adiciona zeros à direita para compensar os dígitos faltantes.
maximumFractionDigits:
- Define o número máximo de dígitos fracionados
- Intervalo de Valores: 0 ~ 20
- Valor Default: 3
const number = 10.175;
number.toLocaleString('pt-br', {style: 'decimal', maximumFractionDigits: 1});
// Output: "10,2"
Aqui, ele arredonda os números de acordo com a regras de arredondamento.
minimumSignificantDigits:
- Define a quantidade mínima de dígitos significantes
- Intervalo de Valores: 1 ~ 21.
- Valor Default: 1
const number = 10.175;
number.toLocaleString('pt-br', {style: 'decimal', minimumSignificantDigits: 10});
// Output: "10,17500000"
Diferente de minimumIntegerDigits, ele não adiciona zeros à esquerda para compensar os dígitos faltantes e sim à direita.
maximumSignificantDigits:
- Define a quantidade máxima de dígitos significantes
- Intervalo de Valores: 0 ~ 20.
- Valor Default:
minimumSignificantDigits
const number = 10.175;
number.toLocaleString('pt-br', {style: 'decimal', maximumSignificantDigits: 2});
// Output: "10"
number.toLocaleString('pt-br', {style: 'decimal', maximumSignificantDigits: 10});
// Output: "10,155"
Estilo percent
Para estilizar números no formato percentual, precisamos definir a propriedade style como percent. Aqui vale lembrar que porcentagem é a divisão de um número qualquer por 100. Então, para:
Exibir valores entre 0% e 100%, onde 100% não está incluso
O valor a ser exibido deve estar entre 0 e 1, onde 1 não está incluso:
const discount = 0.08179;
off.toLocaleString('pt-br', {style: 'percent'});
// Output: 8%
Exibir valores maiores ou iguais a 100%
O valor a ser exibido deve ser maior ou igual a 1:
const discount = 8.179;
discount.toLocaleString('pt-br', {style: 'percent'});
// Output: "818%"
Estilo currency
Para formatar valores monetários, precisamos definir a propriedade style como currency. Além disso, também é preciso usar a propriedade currency definindo seu valor com o código da moeda necessária de acordo com a ISO 4217:
const price = 2865.79;
price.toLocaleString('pt-BR', {style: 'currency', currency: 'BRL'});
// Output "R$ 2.865,79"
price.toLocaleString('ja-JP', {style: 'currency', currency: 'JPY'});
// Output "￥2,866"
price.toLocaleString('en-US', {style: 'currency', currency: 'USD'});
// Output "$2,865.79"
A opção currencyDisplay
Podemos, ainda, definir como este valor será exibido. Valores aceitos:
-
name: exibe nome da moeda -
code: exibe o código de acordo com aISO 4217 -
symbol(default): exibe o símbolo da moeda
const price = 2865.79;
price.toLocaleString('pt-BR', {
style: 'currency',
currency: 'BRL',
currencyDisplay: 'name'
});
// Output "2.865,79 Reais brasileiros"
price.toLocaleString('pt-BR', {
style: 'currency',
currency: 'BRL',
currencyDisplay: 'code'
});
// Output "BRL 2.865,79"
Limitações
A MDN recomenda que, caso exista um volume muito grande de números a serem formatados, é melhor criar um objeto Intl.NumberFormat e usar o método Intl.NumberFormat.prototype.format() para ter um ganho de performance.
Conclusão
Considere o HTML a seguir:
<span class="price"></span>
Sem Number.prototype.toLocaleString(), precisaríamos fazer algo assim para obtermos uma apresentação minimamente aceitável de um valor monetário:
const value = 25.978;
const priceContainer = document.querySelector('.price');
priceValueContainer.innerHTML = `R$ ${value.toFixed(2)}`;
Porém, usando Number.prototype.toLocaleString(), podemos delegar a responsabilidade para o formatador:
priceContainer.innerHTML = value.toLocaleString('pt-BR', {style: 'currency', currency: 'BRL'});
Ok, mas, no final das contas, ambos os códigos geram o mesmo resultado visual. Por que eu deveria usar Number.prototype.toLocaleString() então?
Uma resposta possível seria para o seguinte caso:
Suponha que o nome da moeda do Brasil mude de Reais para Nárnia Reais e que o símbolo deixará de ser R$ para se tornar NR$. A gente teria que sair atualizando tudo manualmente em nossa aplicação. Então, delegar essa responsabilidade para um método Number.prototype.toLocaleString() pode agilizar essas modificações, pois ele usará as atualizações mais recentes dos códigos dos países.
E isso não é apenas para moedas, mas também para outros números. Imagine ter que formatar números grandes como a população ou o PBI de um país, por exemplo?
Então, conhecer esse tipo de método torna-se interessante e um facilitador quando precisamos trabalhar com internacionalização.
Top comments (0)