Função
As máscaras em campos de formulários funcionam como guias para ajudar os usuários durante a inserção de dados. Essas máscaras têm O uso de máscaras tem o objetivo de garantir que os dados inseridos nos campos estejam no formato correto. Normalmente, não há validação dos dados, apenas uma adequação em relação ao formato destes, garantindo que os tipos corretos de caracteres sejam inseridos nos lugares certos. Os usos mais típicos são para datas, horários, números de CPF, números de telefone, moedas, entre outros. Durante a inserção dos dados não formatados pelo usuário, a máscara cuida de adicionar traços e outros separadores em locais apropriados.
Enquanto os dados são inseridos no campo, as máscaras vão adequando o texto na formatação correta. Na figura abaixo foram utilizados os padrões de máscaras do Cronapp, porém é possível criar sua própria máscara seguindo as configurações seguidas nesse texto.
Figura 1 - Exemplo de componentes utilizando máscaras
Além das máscaras, outros fatores podem influenciar em como serão visualizados os campos que utilizam valores de tipo Data e Hora. Para mais detalhes, acesse a documentação Entendendo o funcionamento dos tipos data e hora.
Máscaras
cada caractere do valor seja inserido nos lugares definido pela máscara.
A configuração das máscaras do lado servidor e cliente da aplicação são diferentes. Em geral, quando queremos apresentar um dado mascarado para o usuário em uma view (formulário), usamos as máscaras clientes, e para isso, o Cronapp possui diversos recursos que auxiliam essa configuração, veja mais detalhes em Formatação de máscaras na camada cliente. As máscaras do lado servidor são configuráveis a partir de blocos (servidor) e normalmente são utilizados na criação de textos, relatórios ou qualquer outro conteúdo tratado no lado servidor da aplicação.
Na figura abaixo foram inseridos um valor e uma máscara no bloco Formatar Número, o resultado pode ser visto no Console do Depurador.
Figura 1 - Exemplo de uso de máscaras
Máscaras
Para outros detalhes sobre a utilização das máscaras na camada servidor, acesse a documentação oficial Java Customizing Formats.
Tipo
Máscara
Função
Compatibilidade
Monetário
#.##0,00;0
O usuário poderá digitar uma sequência máxima de seis caracteres numéricos onde o primeiro caractere, que representa a casa de milhar do número, é separado dos três seguintes, que representam a centena, pelo caractere de controle ponto(.). Por sua vez, esses três valores são separados dos dois últimos, que representam a porção decimal, por vírgula (,).
Exemplo: 9.999,99Observação: a depender do tipo, a máscara tem comportamento diferente. Para a máscara em questão, se o tipo for numérico ou inteiro, a quantidade de caracteres antes da vírgula não é limitada. Logo, exemplos como 954.897,01 ou 9,87 são válidos.
Essa máscara funciona quando o campo é do tipo text, number ou integer.
Monetário
0,00;0
O usuário poderá digitar uma sequência máxima de três caracteres numéricos onde o primeiro caractere, que representa a parte inteira do número, é separado dos outros dois, que representam a parte decimal, pelo caractere de controle vírgula (,).
Exemplo: 1,23
Observação: depender do tipo, a máscara tem comportamento diferente. Para a máscara em questão, se o tipo for numérico ou inteiro, a quantidade de caracteres antes da vírgula não é limitada. Logo, exemplos como 954897,01 ou 9,87 são válidos.Essa máscara funciona quando o campo é do tipo text, number ou integer.
Monetário
0;0
O usuário poderá digitar o máximo de um caractere numérico inteiro.
Exemplo: 2
Observação: depender do tipo, a máscara tem comportamento diferente. Para a máscara em questão, se o tipo for numérico ou inteiro, a quantidade de caracteres antes do ponto e vírgula não é limitada. Logo, exemplos como 954, 184654 ou 9 são válidos.Essa máscara funciona quando o campo é do tipo text, number ou integer.
CPF
999.999.999-99;0
O usuário poderá digitar uma sequência máxima de onze caracteres numéricos onde os primeiros 9 caracteres são agrupados de três em três e separados, cada grupo, por ponto (.). Os últimos 2 caracteres são separados dos restantes por traço (-).
Exemplo: 857.354.684-96
Essa máscara funciona quando o campo é do tipo text.
CNPJ
99.999.999/9999-99;0
O usuário poderá digitar uma sequência máxima de quatorze caracteres numéricos onde os dois primeiros caracteres são separados por ponto(.). Os seis caracteres consecutivos são agrupados de três em três e separados por ponto (.) entre si. Os quatro caracteres seguintes são separados dos anteriores por barra (/) e os dois finais por traço (-).
Exemplo: 78.425.986/0036-15
Essa máscara funciona quando o campo é do tipo text.
CEP
99999-999;0
O usuário poderá digitar uma sequência máxima de oito caracteres numéricos onde os cinco primeiros caracteres são separados dos três últimos por traço (-).
Exemplo: 41815-135
Essa máscara funciona quando o campo é do tipo text.
Telefone com DDD
(99) 9999-9999;0
O usuário poderá digitar uma sequência máxima de dez caracteres numéricos onde os dois primeiros caracteres são separados dos demais por espaço ( ) e contidos entre parênteses. Os oito caracteres restantes são agrupados de quatro em quatro e separados entre si por traço (-).
Exemplo: (71) 3450-1440
Essa máscara funciona quando o campo é do tipo text ou tel.
Data
DD/MM/YYYY
Tipo | Máscara | Função |
|---|---|---|
Monetário | ###,###.### | O sinal de cerquilha (#) denota um dígito, a vírgula é um espaço reservado para o separador de milhar e o ponto é um espaço reservado para o separador centavos. Para que o valor desejado apareça depois da vírgula (centavos), é necessário que na entrada ele esteja depois de um ponto, como por exemplo: 350230.67 Exemplo: 350.230,67 |
| Monetário com moeda | ¤###,###.### | O sinal de cerquilha (#) denota um dígito, a vírgula é um espaço reservado para o separador de milhar e o ponto é um espaço reservado para o separador centavos, O sinal (¤) será substituído pelo símbolo da moeda local, se usado 2 juntos, será utilizado a moeda internacional (dolar). Para que o valor desejado apareça depois da vírgula (centavos), é necessário que na entrada ele esteja depois de um ponto, como por exemplo: 350230.67 Exemplo: R$350.230,67 |
Data | dd.MM.aa |
O usuário poderá digitar uma sequência máxima de 8 caracteres numéricos para: DD (representa os dois dígitos do dia), MM (representa os dois dígitos do mês) e YYYY (representa os 4 dígitos do ano). Exemplo: 06/10/2017 |
Essa máscara funciona quando o campo é do tipo date.
Data e Hora |
dd.MM.yy H:mm:ss | O usuário poderá digitar uma sequência máxima de 8 caracteres numéricos para: DD (representa os dois dígitos do dia), MM (representa os dois dígitos do mês) e YYYY (representa os 4 dígitos do ano). Para a representação da hora com dois dígitos é usado os caracteres (HH) separados por dois pontos (:) da representação de minuto (mm) e segundo (ss). Exemplo: 01/10/ |
18 15:55:40 |
Essa máscara funciona quando o campo é do tipo date and time.
| Informações |
|---|
Caso o usuário decida por não utilizar máscaras e opte por definir apenas a propriedade Tipo do componente, as máscaras aplicadas terão como base o idioma padrão sendo utilizado no navegador. |
Exemplos
Alimentando o campo já com máscara
É possível inserir um conteúdo já com máscara em um componente visual. Ao clicar no botão que abre a janela conteúdo de qualquer propriedade, é possível encontrar os campos Tipo e Máscara em todas as abas: Texto, Expressão, Campo de Tela e Bloco de Programação. O campo Máscara também permite que você defina sua própria máscara.
Figura 2 - Alimentando um campo com o retorno do bloco de programação já com máscara
Estrutura de uma máscara
As máscaras que podem ser aplicadas aos campos são divididas, em sua grande maioria, em duas seções:
<seção1>;<seção2>
<seção1>: A máscara propriamente dita. Esta máscara é composta por caracteres especiais, também conhecidos como caracteres de controle, utilizados para formatar os dados a serem inseridos num determinado campo.
Ex: 0,00;0
<seção2>: Valor que define se a máscara aplicada aos dados do campo será armazenada no banco de dados. Para que os dados não sejam armazenados com a máscara, utiliza-se o valor zero (0) após o caractere ponto e vírgula (;); para que sejam armazenados com a máscara, utiliza-se o valor um (1).
Ex: 0,00;0
Valores numéricos
Caracteres utilizados na elaboração de máscaras para valores numéricos.
Caractere
Descrição
0 ou 9
Aceita apenas números (dígito).
#
Aceita apenas números (dígito).
Ponto (.)
Utilizado como separador/agregador de dígitos. Ao renderizar o valor final, o Cronapp vai usar o caractere de milhar correspondente ao idioma da aplicação.
Vírgula (,)
Utilizado como separador para o(s) dígito(s) que representa(m) a parte decimal de um número. Ao renderizar o valor final, o Cronapp vai usar o caractere de separação decimal correspondente ao idioma da aplicação.
Ponto e vírgula (;)
Separa as duas seções da máscara.
Qualquer outro caractere inserido irá aparecer no campo de entrada de texto na mesma posição definida na máscara.
Exemplo: R$ #.##0,00;0 que resulta em valores como R$ 234.677,98
| Dica |
|---|
Para formatação de CPF ou CNPJ, é recomendado utilizar a camada cliente. |
Símbolo e separadores
Dentro dos subpadrões, você especifica a formatação com símbolos especiais. Esses símbolos são descritos na tabela a seguir:
| Símbolo | Descrição |
|---|---|
| 0 | um dígito |
| # | um dígito, zero mostra como ausente |
| . | espaço reservado para separador decimal |
| , | marcador de posição para separador de agrupamento |
| E | separa mantissa e expoente para formatos exponenciais |
| ; | separa formatos |
| - | prefixo negativo padrão |
| % | multiplique por 100 e mostre como porcentagem |
| ? | multiplique por 1000 e mostre por mil. |
| ¤ | sinal de moeda; substituído pelo símbolo da moeda; se duplicado, substituído por símbolo de moeda internacional; se presente em um padrão, o separador decimal monetário é usado em vez do separador decimal |
| X | quaisquer outros caracteres podem ser usados no prefixo ou sufixo |
| ' | usado para citar caracteres especiais em um prefixo ou sufixo |
Datas e/ou horas
Sintaxe do padrão de formato de data.
Para outros detalhes sobre a utilização das máscaras na camada servidor, acesse a documentação oficial Java Customizing Formats Dates and Times.
| Símbolo | Significado | Exemplo |
|---|---|---|
| G | designador de era | AD |
| y | ano | 2009 |
| M | mês no ano | Julho e 07 |
| d | dia do mês | 10 |
| h | hora em am / pm (1-12) | 12 |
| H | hora do dia (0-23) | 0 |
| m | minuto em hora | 30 |
| s | segundo em minuto | 55 |
| S | milissegundo | 978 |
| E | dia da semana | terça |
| D | dia no ano | 189 |
| F | dia da semana no mês | 2 (2ª quarta de julho) |
| w | semana no ano | 27 |
| W | semana no mês | 2 |
| a | marcador am / pm | PM |
| k | hora do dia (1-24) | 24 |
| K | hora em am / pm (0-11) | 0 |
| z | fuso horário | Horário padrão do Pacífico |
| ' | escape para texto | (Nenhum) |
Exemplos de máscaras no Servidor:
Observação: diferente das máscaras textuais, as numéricas não limitam a quantidade de números antes da vírgula (parte inteira). Para limitar, use o tipo texto. O uso do tipo do campo como texto não determina que o tipo de dados é texto e sim que o tipo de máscara usada será a textual e o conteúdo continuará sendo numérico, caso ele seja associado a um atributo número do datasource.Exemplo: para a máscara #.##0,00;0.
- Se o tipo for numérico, valores como 923.535.342,98 - 9,90 - 3.343,56 são aceitos ou formatados.
- Se o tipo for texto, apenas o uso restrito de caracteres informados será aceito.
- Ex: 3.343,56 - 9.987,98.
Datas e/ou horas
Caracteres utilizados na elaboração de máscaras para datas e/ou horas.
Caractere
Descrição
D
Aceita valores numéricos inteiros referentes ao dia da data.
M
Aceita valores numéricos inteiros referentes ao mês da data.
Y
Aceita valores numéricos inteiros referentes ao ano da data.
H
Aceita valores numéricos inteiros referentes à hora.
m
Aceita valores numéricos inteiros referentes ao minuto.
s
Aceita valores numéricos inteiros referentes ao segundo.
Barra (/)
Utilizado como separador de dia, mês e ano ou valores numéricos em geral.
| Nota |
|---|
Campos de entrada contendo máscaras para valores do tipo data e/ou hora devem ter, além da máscara preenchida, a propriedade Tipo definida de acordo com máscara. Esse Tipo permite a utilização do componente de calendário para seleção de uma data. Exemplo: Para a máscara: DD/MM/YYYY o tipo definido para o campo deve ser Data. |
Valores alfanuméricos
Caracteres utilizados na elaboração de máscaras para valores alfanuméricos.
Caractere
Descrição
A
Caracteres alfanuméricos (A-Z, a-z, 0-9).
Qualquer outro caractere
Qualquer outro caractere inserido irá aparecer no campo de entrada de texto na mesma posição definida na máscara.
Exemplo: PL-AA000 que resulta em valores como PL-qe342
Combinação de caracteres
É possível elaborar e combinar caracteres para que as máscaras apresentem outras visualizações ao inserir os dados nos campos.
Representação de data
Caracteres utilizados para elaboração de máscaras a serem aplicadas na representação de data.
Entrada
Exemplo
Descrição
Resultado na máscara
D DD
1...31
Representa de forma numérica o dia do mês com um ou dois dígitos. Caso apenas um caractere D seja usado na máscara, os números entre 1...9 são representados apenas com um dígito. Caso seja utilizado dois caracteres DD, os números entre 1...9 são representados com dois dígitos.
Ex.:04
D/MM/YYYY - 1/12/2018
DDD DDDD
1...365
Representa de forma numérica o dia do ano. Caso apenas três caracteres DDD sejam usados na máscara, os números serão representados com sua respectiva quantidade de dígitos. Caso sejam utilizados quatro caracteres DDDD, qualquer número definido terá pelo menos três dígitos.
Ex.: Utilizando o padrão DDDD para a data 4/11/2018, a exibição será: 004/11/2018.
DDD/MM/YYYY - 261/09/2018
Do
1º...31º
Representa de forma numérica e ordinal o dia do mês.
Do/MM/YYYY - 14º/04/2018
M MM
1...12
Representa de forma numérica os meses do ano com um ou dois dígitos. Caso apenas um caractere M seja usado na máscara, os números entre 1...9 são representados apenas com um dígito. Caso seja utilizado dois caracteres MM, os números entre 1...9 são representados com dois dígitos.
Ex.:04
DD/MM/YY - 01/08/18
MMM MMMM
Jan...Dezembro
Exibe o nome do mês abreviado com 3 letras (MMM) ou de forma completa (MMMM).
Ex.: DD/MMMM/YYYY- 11/December/2017
DD/MMM/YY - 21/Jun/2018
Mo
1º...12º
Representa de forma numérica e ordinal o mês referente a data.
DD/Mo/YYYY - 14/4º/2018
Q
1...4
Exibe o trimestre do ano referente a data escolhida.
DD/MM/YY Q - 13/07/18 3
YY
18
Ano com dois dígitos.
DD/MM/YY - 06/10/18
YYYY
2018
Ano com quatro dígitos.
D/MM/YYYY - 1/09/2018
Representação de horário
Caracteres utilizados para elaboração de máscaras a serem aplicadas na representação de horário.
Entrada
Exemplo
Descrição
Resultado na máscara
H HH
0...23
Convenção de hora adotada onde o dia é dividido em 24 horas(24h) iniciando a partir da hora zero(0). Caso apenas um caractere H seja usado na máscara, os números entre 1...9 são representados apenas com um dígito. Caso seja utilizado dois caracteres HH, os números entre 1...9 são representados com dois dígitos.
Ex.:04
HH:mm:ss - 09:08:06
h hh
1...12
Convenção de hora adotada onde o dia é divido em dois períodos de 12 horas cada, ante meridiem (a.m.) e post meridiem (p.m.) (usados em conjunto da entrada a A). Caso apenas um caractere h seja usado na máscara, os números entre 1...9 são representados apenas com um dígito. Caso seja utilizado dois caracteres hh, os números entre 1...9 são representados com dois dígitos.
Ex.:04
hh:mm:ss a - 04:09:19 am
a A
am pm
Ante meridiem (a.m.) e post meridiem (p.m.).
hh:mm:ss a- 04:09:19 pm
m mm
0...59
Representação de minuto. Caso apenas um caractere m seja usado na máscara, os números entre 1...9 são representados apenas com um dígito. Caso seja utilizado dois caracteres mm, os números entre 1...9 são representados com dois dígitos.
Ex.:04
h:mm:ss- 8:31:19
s ss
0...59
Representação de segundo. Caso apenas um caractere s seja usado na máscara, os números entre 1...9 são representados apenas com um dígito. Caso seja utilizado dois caracteres ss, os números entre 1...9 são representados com dois dígitos.
Ex.:04
h:mm:ss- 8:31:19
Camada Servidor:
Na camada Servidor, Adicionaremos à função "Executar" o bloco Alterar valor do campo e no parâmetro Campo inserimos um componente de exemplo para inserir a máscara, usaremos o Entrada de texto, em seguida, no parâmetro Valor iremos inserir o bloco Formatar data, que em seu parâmetro Data inserimos o bloco Obter data atual sem hora e por fim, no parâmetro Máscara, inserimos o formato "MM-dd-yyyy", onde "MM" é o mês em 2 digitos, "dd" é o dia em 2 dígitos e "yyyy" é o ano em 4 digitos, verifique o resultado na figura 5.
Figura 4 - Configurando a máscara através do bloco Formatar data Servidor
Figura 5 - Retorno da função apresentada na figura 4
| Entrada | Exemplo |
|---|---|
| dd-MM-yy | 31-01-12 |
| dd-MM-yyyy | 31-01-2012 |
| MM-dd-yyyy | 01-31-2012 |
| yyyy-MM-dd | 2012-01-31 |
| yyyy-MM-dd HH:mm:ss | 2012-01-31 23:59:59 |
| yyyy-MM-dd HH:mm:ss.SSS | 2012-01-31 23:59:59.999 |
| yyyy-MM-dd HH:mm:ss.SSSZ | 2012-01-31 23:59:59.999+0100 |
| EEEEE MMMMM yyyy HH:mm:ss.SSSZ | Saturday November 2012 10:45:42.720+0100 |
| dd/MM/yyyy | 31/01/2012 |
| dd/MM/yyyy HH:mm:ss | 31/01/2012 23:59:59 |
Blocos de programação
O bloco de programação fornece algumas funções para tratamento de datas. Algumas das mais importantes são:
- Formatar número: formata o número de acordo com a máscara do tipo servidor.
- Formatar número com localidade: formata o número de acordo com a máscara do tipo servidor, podendo configurar o retorno para os padrões PT-BR.
- Obter valor do campo: obtém o valor de qualquer campo da tela cliente no servidor.
- Obter campo (Banco de Dados): essa função obtém o campo do banco de dados que sempre estará no fuso especificado para a aplicação.
- Exibir Notificação: essa função bem comum merece uma observação importante, ao exibir uma data. Caso você não formate a data, ela será exibida no fuso horário do cliente.
- Imprimir: imprime no console do depurador os números já formatados.
- Converter Texto para Data: essa função converterá um texto (representação textual de uma data) para um objeto data. Caso uma máscara seja informada, ela a usará para tentar fazer a conversão, caso contrário, algumas máscaras predefinidas serão usadas - levando em consideração o idioma do cliente. Caso o formato textual não considere o fuso na sua escrita (ex.: 12/03/1910), o fuso padrão do servidor será usado. Caso o fuso tenha sido especificado (ex.: 2019-09-22T02:30Z), ele será usado.
- Converter Texto para Data com Fuso Horário: tem o mesmo comportamento da função acima, porém, quando o fuso não está discriminado, ele usa o especificado pelo parâmetro de fuso da função.
- Formatar Data: formata uma data a partir da máscara e do idioma selecionado.
- Formatar Data com Fuso Horário: formata uma data a partir do fuso horário, máscara e do idioma selecionado.
Exemplos
Máscara com data
Abaixo, na figura 2, segue um exemplo do uso da máscara na camada Servidor, observe que no parâmetro Máscara inserimos o formato "MM-dd-yyyy", onde "MM" é o mês em 2 dígitos, "dd" é o dia em 2 dígitos e "yyyy" é o ano em 4 dígitos, verifique o resultado impresso no Console do Depurador.
Figura 2 - Configurando a máscara através do bloco Formatar data Servidor
Máscara com moedas
Na função abaixo, o bloco Formatar Número com Localidade recebe um valor (em Conteúdo) e mais 3 argumentos Máscara, Língua e País, é retornado no console o valor monetário do mesmo.
Figura 3 - Exemplo monetário
Nesta página
| Índice | ||||
|---|---|---|---|---|
|
Conteúdo complementarExibir filhos