NumberFormatter - com escopo, global

  • Versão de lançamento: Xanadu
  • Atualizado 1 de ago. de 2024
  • 4 min. de leitura

    • A API NumberFormatter inclui métodos que retornam números formatados de acordo com o idioma do usuário atual.

    Esta API está disponível em apps com escopo e globais e é executada no namespace sn_i18n.

    Quando formatados por idioma ou localidade, os usuários podem exibir os números conforme o esperado. Por exemplo, se a localidade for fr (francês), um valor fornecido como 100.00 retornará como 100,00.

    NumberFormatter – format(Número número)

    Retorna uma representação de cadeia de caracteres de um número formatado de acordo com a configuração de idioma do usuário atual.

    Tabela 1. Parâmetros
    Nome Tipo Descrição
    número Número Número de qualquer tamanho.
    Tabela 2. Retorna
    Tipo Descrição
    Cadeia de caracteres Número formatado de acordo com a configuração de idioma do usuário atual.

    O exemplo a seguir mostra os resultados retornados para um usuário com o idioma definido como espanhol.

    gs.info("Number is: " + sn_i18n.NumberFormatter.format(123456.789));
gs.info("Number is: " + sn_i18n.NumberFormatter.format(-123456.789));

    Saída:

    Number is: 123.456,789
Number is: -123.456,789

    NumberFormatter – formatLang(Número numérico, Idioma da cadeia de caracteres)

    Retorna uma representação de cadeia de caracteres de um número formatado de acordo com o idioma passado como um parâmetro.

    Tabela 3. Parâmetros
    Nome Tipo Descrição
    número Número Número de qualquer tamanho.
    idioma Cadeia de caracteres Marcador de idioma em conformidade com IETF BCP-47.
    Tabela 4. Retorna
    Tipo Descrição
    Cadeia de caracteres Número formatado de acordo com o idioma passado como um parâmetro.

    O exemplo a seguir mostra a saída para a configuração de idioma alemão.

    gs.info("Number is: " + sn_i18n.NumberFormatter.formatLang(123456.789, "de-de"));
gs.info("Number is: " + sn_i18n.NumberFormatter.formatLang(-123456.789, "de-de"));

    Saída:

    Number is: 123.456,789
Number is: -123.456,789

    NumberFormatter - parseWithLocale(cadeia de caracteres número, idioma da cadeia de caracteres, país da cadeia de caracteres)

    Analisa um número de uma cadeia de caracteres de texto passada, da esquerda para a direita, para extrair o valor numérico. Em seguida, ele usa os códigos de país e idioma aprovados para identificar a localidade do número e retorna o número analisado nesse formato.

    Este método analisa a cadeia de caracteres até que ela atinja um caractere que não reconhece como um valor numérico ou um separador de moeda.

    Tabela 5. Parâmetros
    Nome Tipo Descrição
    número Cadeia de caracteres Cadeia de caracteres a ser analisada. Esta cadeia de caracteres pode conter valores numéricos e separadores de moeda, como vírgulas e pontos decimais. Por exemplo: "24,506.55" ou "45.677,89".
    idioma Cadeia de caracteres Código de idioma ISO-639 de dois caracteres.
    país Cadeia de caracteres Código de país ISO-3166 de dois caracteres.
    Tabela 6. Retorna
    Tipo Descrição
    Número Número analisado no formato da localidade especificada.

    Lança uma exceção se o primeiro caractere da cadeia de caracteres não puder ser analisado.

    Por exemplo:
    • "123,34": analisa até 123,34, desde que o separador decimal de localidade seja um ponto.
    • "1.234,56": analisa até 1234,56, desde que o separador de agrupamento de localidades seja uma vírgula e o separador decimal seja um ponto.
    • "1.234.567,89": se o separador de agrupamento não for um ponto, será analisado como 1.
    • "123x456": analisa até 123.
    • "text123": faz com que o método emita um "ParseException".

    O exemplo de código a seguir demonstra a análise de cadeias de caracteres para várias localidades, bem como a análise de uma cadeia de caracteres com separadores inesperados. O último exemplo analisa apenas parcialmente a cadeia de caracteres porque um espaço não é um separador válido.

    var x = sn_i18n.NumberFormatter.parseWithLocale("48,837.77", "en", "US");
var y =  sn_i18n.NumberFormatter.parseWithLocale("77.931,22", "de", "DE");
var z = sn_i18n.NumberFormatter.parseWithLocale("562 339,89", "fr", "FR");
var specialCase = sn_i18n.NumberFormatter.parseWithLocale("400 797,67", "en", "US");

gs.info(x);
gs.info(y);
gs.info(z);
gs.info(specialCase);

    Saída:

    48837.77
77931.22
562339.89
400

    NumberFormatter - parseWithSeparators(cadeia de caracteres número, agrupamento de cadeias de caracteresSeparator, cadeia de caracteres decimalSeparator)

    Analisa e retorna um número de uma cadeia de caracteres de texto passada, percorrendo da esquerda para a direita, até encontrar um caractere que não pode ser analisado. Os valores analisáveis incluem números e o agrupamento especificado e os separadores decimais.

    Tabela 7. Parâmetros
    Nome Tipo Descrição
    número Cadeia de caracteres Cadeia de caracteres a ser analisada. Esta cadeia de caracteres pode conter valores numéricos e os separadores especificados, como vírgulas e pontos decimais. Por exemplo: "24,506.55" ou "45.677,89".
    agrupamentoSeparador Cadeia de caracteres Caractere que denota o separador de agrupamento, também conhecido como separador de milhares, na cadeia de caracteres passada.

    Por exemplo: vírgula ",", ponto "." ou espaço " ".
    decimalSeparator Cadeia de caracteres Caractere que denota o separador decimal na cadeia de caracteres passada.

    Por exemplo: vírgula ",", ponto "." ou espaço " ".
    Tabela 8. Retorna
    Tipo Descrição
    Número Número analisado.

    Lança uma exceção se o primeiro caractere da cadeia de caracteres não puder ser analisado.

    Por exemplo:
    • "123,34": analisa até 123,34, desde que o separador decimal de localidade seja um ponto.
    • "1.234,56": analisa até 1234,56, desde que o separador de agrupamento de localidades seja uma vírgula e o separador decimal seja um ponto.
    • "1.234.567,89": se o separador de agrupamento não for um ponto, será analisado como 1.
    • "123x456": analisa até 123.
    • "text123": faz com que o método emita um "ParseException".

    O exemplo de código a seguir mostra como analisar números usando vários separadores. Observe que o exemplo de análise final analisa somente os três primeiros dígitos do número, já que um espaço não é um separador válido.

    var x = sn_i18n.NumberFormatter.parseWithSeparators('48,837.77', ',', '.');
var y =  sn_i18n.NumberFormatter.parseWithSeparators('77.931,22', '.', ',');
var z = sn_i18n.NumberFormatter.parseWithSeparators('562 339,89', ' ', ',');
var specialCase = sn_i18n.NumberFormatter.parseWithSeparators('400 797,67', '.', ',');

gs.info(x);
gs.info(y);
gs.info(z);
gs.info(specialCase);

    Saída:

    48837.77
77931.22
562339.89
400