Configurações - Máscaras de Formulário

O que é

Esta página reúne os padrões de formatação (as "máscaras") que você pode aplicar aos campos dos formulários de cadastro: CPF, CNPJ, telefone, CEP, placa de veículo, data, valores em reais e outros. Elas ficam organizadas em cards por categoria (Data, Documento, Telefone, Financeiro, Endereço, Veículo, Número, Contato, Outro) e cada uma mostra o nome, o padrão de digitação, um exemplo formatado e se é uma máscara do Sistema ou uma que você mesmo criou (Custom).

Você chega aqui clicando no botão Gerenciar Máscaras dentro de Configurações > Formulários. É o lugar certo quando você precisa de um formato de campo que ainda não existe - por exemplo, para um campo personalizado que criou para guardar um número de contrato ou uma matrícula com formato próprio.

Como usar

1. Vá em Configurações > Formulários no menu lateral e clique no botão Gerenciar Máscaras no cabeçalho da página.
2. Na tela Máscaras de Campo, percorra os cards por categoria para ver as máscaras já disponíveis, com Slug, Padrão, Exemplo e Tipo.
3. Para criar uma nova, clique em Nova Máscara (canto superior direito) e preencha:
   • Nome - identifica a máscara nas listas de seleção (ex: "Matrícula Escolar").
   • Padrão (IMask) - a sequência que define o formato. Use 0 para número, a para letra e * para qualquer caractere (o texto de ajuda abaixo do campo mostra essa regra).
   • Exemplo - um valor de exemplo já formatado, mostrado nas listas.
   • Categoria - agrupa a máscara em um dos cards (Documento, Telefone, Financeiro etc.).
   • Descrição - texto opcional explicando para que serve.
4. Clique em Criar Máscara. Ela aparece na lista com a tag Custom e um slug próprio, gerado automaticamente a partir do nome.
5. Para usar a máscara num campo, volte para Configurações > Formulários, escolha a entidade e o contexto Admin, e selecione a máscara na coluna Máscara do campo padrão desejado - ou associe-a a um campo personalizado na hora de criá-lo.
6. Para editar uma máscara Custom, clique no ícone de lápis na linha dela e ajuste os mesmos campos; clique em Atualizar.
7. Para remover, clique no ícone de lixeira e confirme em Tem certeza que deseja remover a máscara "X"?.

O que você precisa saber antes

• Todas as máscaras do Sistema seguem o padrão brasileiro. CPF, CNPJ, CPF/CNPJ automático, RG, Cadastur, telefone celular e fixo com DDD, CEP e placa (Mercosul e antiga) só existem no formato usado no Brasil. Não há, prontas, versões para documento ou telefone de outro país. Se a sua empresa atende clientes que moram fora do Brasil, o caminho é criar uma máscara personalizada com um padrão mais aberto (por exemplo, usando * para aceitar qualquer caractere) para esse campo específico.
• O telefone e o endereço da sua própria empresa não passam por aqui. Essa configuração vale para os campos de Clientes, Dependentes, Guias e demais cadastros. Os dados de contato da empresa (que mudam de formato quando ela está fora do Brasil) ficam em Configurações > Empresa, numa tela separada.
• Nem toda máscara formata o campo enquanto você digita. CPF e Telefone já têm formatação própria embutida no sistema (tanto no cadastro de clientes quanto no formulário do site) e continuam se formatando normalmente independente do que estiver configurado aqui. As demais - CEP, placa, Cadastur, valores em reais, percentual e qualquer máscara personalizada que você criar - servem principalmente como referência de formato e para exibir o valor já salvo de um jeito legível (por exemplo, no card "Informações" da página pública da viagem). Elas não impedem nem obrigam a digitação num formato específico.
• Editar ou remover uma máscara Custom não muda dado nenhum já salvo. O que já foi digitado nos cadastros continua exatamente como está gravado; só muda como esse valor aparece formatado depois, e apenas nos lugares que consultam a máscara pelo nome dela.
• Máscaras do tipo Sistema são protegidas. Não têm os ícones de editar e remover - a coluna Ações mostra apenas "Protegido". Se precisar de uma variação (por exemplo, um formato de CPF diferente), crie uma máscara Custom nova em vez de tentar alterar a do Sistema.

Casos especiais

Nenhuma máscara cadastrada

Se a lista de máscaras aparecer vazia (algo raro, só acontece em instalações muito antigas), a tela mostra o aviso Nenhuma máscara cadastrada com a orientação de rodar o carregamento padrão do sistema. Nesse caso, abra um chamado com o suporte em vez de tentar recriar manualmente todas as máscaras de sistema.

Excluir uma máscara em uso

O sistema não bloqueia a exclusão de uma máscara Custom que já esteja associada a algum campo. Se você remover uma máscara em uso, o campo continua funcionando normalmente - ele só deixa de mostrar o valor salvo formatado, exibindo o dado cru.

Erros comuns e como resolver

• "Máscaras do sistema não podem ser editadas." - Causa: tentou editar uma máscara com a tag Sistema. Solução: crie uma máscara Custom com o ajuste que você precisa.
• "Máscaras do sistema não podem ser removidas." - Causa: tentou excluir uma máscara Sistema. Solução: máscaras Sistema não podem ser apagadas; use uma Custom se precisar de outro formato.
• Campos obrigatórios em branco no formulário de Nova Máscara - Causa: Nome, Padrão, Exemplo e Categoria são obrigatórios. Solução: preencha os quatro antes de clicar em Criar Máscara.

Onde encontrar

• URL: /admin/configuracoes/formularios/mascaras
• Caminho no menu: Configurações > Formulários, botão Gerenciar Máscaras no cabeçalho
• Permissão necessária: ver as configurações (acessar) e editar as configurações (criar, editar e remover máscaras)
• Módulo necessário: nenhum

Veja também

• Configurações - Formulários - aplicar a máscara num campo padrão ou personalizado, e configurar visibilidade e obrigatoriedade dos campos.