Máscara de campo Componentes

O que é

Ninguém gosta de adivinhar se o telefone vai com parênteses ou se o CPF leva ponto. Com a máscara, a pessoa digita só os números e o campo coloca a pontuação sozinho, no lugar certo, e não deixa passar do tamanho. Você escreve sw-mask="nome-do-formato" no <input>. Tem formatos brasileiros prontos (CPF, CNPJ, CPF-ou-CNPJ, telefone, CEP, data, hora, cartão, dinheiro) e você pode criar o seu com símbolos simples: # para número, A para letra.

Precisa do CSS e do JavaScript do SWCore. A cada tecla, o SWCore pega o que foi digitado, tira o que não serve (letras num CPF, por exemplo) e escreve de novo já formatado. Nos formatos de número, o celular abre o teclado numérico sozinho. Os números "limpos" (sem pontuação) ficam guardados no atributo data-sw-mask-value do campo, prontos para o seu código usar.

Quando usar

• Cadastro de cliente: CPF, telefone, CEP e data de nascimento.
• Cadastro de empresa ou nota fiscal: CNPJ — ou document, que aceita CPF e CNPJ no mesmo campo.
• Preço e valores no painel da loja: dinheiro (com "R$") ou valor (sem).
• Agendamento: data e hora.
• Códigos seus (placa de carro, RG, código de produto): máscara própria com sw-mask="custom".
• A máscara só arruma o formato. Para avisar "campo obrigatório" ou "CPF incompleto", junte com a Validação inline ou a Validação de formulário.

Comece aqui

1. 1

   Coloque o SWCore na página: o CSS no <head> e o JavaScript antes de fechar o </body>.

   <link rel="stylesheet" href="https://swcore.sanweb.com.br/dist/2.1.0/swcore.min.css">
   <!-- … sua página … -->
   <script src="https://swcore.sanweb.com.br/dist/2.1.0/swcore.min.js"></script>

2. 2

   Escreva sw-mask com o formato no input. Digite só os números.

   WhatsApp

   <div sw-fld>
     <label for="tel">WhatsApp</label>
     <input sw-inp id="tel" name="tel" sw-mask="telefone" placeholder="(81) 99999-0000">
   </div>

Todas as variações

Cada quadro abaixo é o componente de verdade, rodando. O código embaixo é exatamente o que está no quadro: copie e cole.

Tabela de opções

Receitas prontas — usos reais

Situações que aparecem em quase todo site. Copie a que servir.

<form sw-frm action="/clientes" method="post">
  <div sw-frm-row>
    <div sw-fld>
      <label for="cpf">CPF</label>
      <input sw-inp id="cpf" name="cpf" sw-mask="cpf" placeholder="000.000.000-00">
    </div>
    <div sw-fld>
      <label for="nasc">Nascimento</label>
      <input sw-inp id="nasc" name="nasc" sw-mask="data" placeholder="dd/mm/aaaa">
    </div>
  </div>
  <div sw-frm-row>
    <div sw-fld>
      <label for="cel">Celular</label>
      <input sw-inp id="cel" name="cel" sw-mask="telefone" placeholder="(81) 99999-0000">
    </div>
    <div sw-fld>
      <label for="cep">CEP</label>
      <input sw-inp id="cep" name="cep" sw-mask="cep" placeholder="00000-000">
    </div>
  </div>
  <div sw-frm-act><button sw-btn="pri" type="submit">Salvar cliente</button></div>
</form>

<input sw-inp id="cep" sw-mask="cep" placeholder="00000-000">

<script>
  const cep = document.getElementById('cep');
  cep.addEventListener('sw:mask-input', (e) => {
    // e.detail.value = "50030-000" (na tela) · e.detail.raw = "50030000" (só números)
    if (e.detail.raw.length === 8) {
      fetch('https://viacep.com.br/ws/' + e.detail.raw + '/json/')
        .then((r) => r.json())
        .then((end) => console.log(end.logradouro));
    }
  });

  // em qualquer momento:
  SW.Mask.raw(cep);          // "50030000"
  cep.dataset.swMaskValue;   // "50030000"
</script>

<input sw-inp id="preco" name="preco" sw-mask="dinheiro">

<script>
  // o banco guardou 159990 (centavos) → aparece "R$ 1.599,90"
  SW.Mask.set('#preco', '159990');
</script>

<!-- 1) registre o formato uma vez, ANTES do SWCore iniciar a página -->
<script src="https://swcore.sanweb.com.br/dist/2.1.0/swcore.min.js"></script>
<script>
  SWMask.addMask('processo', '#######-##.####.#.##.####');
</script>

<!-- 2) use o nome em qualquer campo -->
<input sw-inp sw-mask="processo" placeholder="0000000-00.0000.0.00.0000">

Eventos

API (JavaScript)

Precisa de quê

• swcore.min.css e swcore.min.js.

Cuidados — erros comuns

• A máscara funciona em <input>. Em <textarea> ela não faz nada.
• Não use type="number" num campo com máscara: esse tipo não aceita ponto, traço nem parênteses. Deixe type="text" (ou type="tel" no telefone).
• O formato registrado com addMask precisa existir antes do SWCore montar a página. Se registrar depois, chame SW.reinit() para os campos com o nome novo começarem a funcionar.
• No dinheiro/valor, os números "limpos" são os centavos: "R$ 1.234,56" vira 123456. Divida por 100 no servidor.
• O formato enviado ao servidor é o da tela (com pontos e traços). Se o seu banco guarda só números, limpe no servidor ou use data-sw-mask-value.
• Não coloque sw-mask e sw-matinp-mask no mesmo campo.

O que ele não faz

• Só formata: não diz se o CPF/CNPJ existe ou se a data é válida (31/02 passa). Para conferir, use Validação inline ou Validação de formulário.
• Editar no meio do texto joga o cursor para o fim a cada tecla. Funciona bem para quem digita em sequência; para corrigir um número no meio, apague e digite de novo.
• O * da máscara própria aceita só letras e números — símbolos digitados são descartados.