Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Intl.NumberFormat: opções de moeda e percentagem

Formata montantes e proporções de acordo com as definições regionais. Descobre quando é obrigatório indicar o código da moeda, por que razão 0,125 representa 12,5% e como controlar as casas decimais.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

new Intl.NumberFormat(locale, { style: "currency", currency: "USD" }).format(amount)
new Intl.NumberFormat(locale, { style: "percent", minimumFractionDigits: 1, maximumFractionDigits: 1 }).format(ratio)

new Intl.NumberFormat(locale, options) cria um formatador reutilizável; format(value) devolve texto localizado. As definições regionais influenciam, por exemplo, os separadores e a posição dos símbolos. style escolhe o tipo de apresentação e, por omissão, tem o valor "decimal".

Com style: "currency", indica em currency um código como "USD". Passa o montante na unidade monetária principal, não em cêntimos: a formatação não converte moedas. A ausência de código lança um TypeError; um código que não seja composto por três letras ASCII lança um RangeError. Um código bem formado não está necessariamente atribuído a uma moeda. currencyDisplay seleciona "symbol" (valor por omissão), "narrowSymbol" (símbolo curto), "code" ou "name". currencySign tem o valor "standard" por omissão; "accounting" pode mostrar montantes negativos entre parênteses, conforme as definições regionais.

Com style: "percent", passa uma proporção: a formatação multiplica-a por 100 antes de a arredondar. Para apresentar 12,5%, passa 0.125, não 12.5. Com a notação padrão e sem definir algarismos significativos, o número predefinido de casas decimais depende da unidade fracionária da moeda (duas para USD); para percentagens é zero. minimumFractionDigits acrescenta zeros se necessário; maximumFractionDigits limita as casas decimais no arredondamento. Com a definição por omissão trailingZeroDisplay: "auto", atribui o mesmo valor a ambas as opções para mostrar exatamente esse número de casas decimais. Com trailingZeroDisplay: "stripIfInteger", a parte decimal é omitida se o resultado arredondado for um número inteiro.

Os dados regionais e o suporte do ambiente de execução podem variar. Os espaços e símbolos podem diferir mesmo com as mesmas definições regionais, pelo que deves evitar comparar todo o texto localizado com um valor fixo. Usa formatToParts() para inspecionar os componentes por tipo.

Exemplos

const locale = "en-US-u-nu-latn";
const money = new Intl.NumberFormat(locale, {
  style: "currency",
  currency: "USD",
  currencyDisplay: "code",
});
const percent = new Intl.NumberFormat(locale, {
  style: "percent",
  minimumFractionDigits: 1,
  maximumFractionDigits: 1,
});

const moneyParts = money.formatToParts(19.9);
const percentParts = percent.formatToParts(0.125);
const valueOf = (parts, type) => parts.find(part => part.type === type)?.value;

console.log(JSON.stringify([
  valueOf(moneyParts, "currency"),
  valueOf(moneyParts, "integer"),
  valueOf(moneyParts, "fraction"),
]));
console.log(JSON.stringify([
  valueOf(percentParts, "integer"),
  valueOf(percentParts, "fraction"),
  percentParts.some(part => part.type === "percentSign"),
]));

Resultado

["USD","19","90"]
["12","5",true]

A primeira linha apresenta o código USD e as duas partes do montante, incluindo o zero final. A segunda mostra as partes numéricas de 12,5% e confirma a presença de um sinal de percentagem sem verificar o carácter exato nem a sua posição.

Lições relacionadas

  • JavaScript · Lição 24 · Intermédio · Versão: 3

Fontes