Mask

• Introdução
• Exemplo básico
• Máscaras
  • Tokens integrados
  • Escapando integrados
• Modos
  • Modo Shift & replace
  • Modo Select
• Tokens
  • Criando novos tokens
  • Modificar tokens
  • Tokens de caracteres
  • Tokens Enum
• Grupos
  • Opções de grupo
• Prefixo & sufixo
• Executando a máscara ao contrário
• Valores da máscara
  • Valores incompletos
  • Valores sem máscara
• Ocultando a máscara
• Sobreposição (colorindo uma máscara)
• Props & Atributos
• Seções
• Acessibilidade
  • Interações com o Teclado

Introdução

A entrada com mask (máscara) transforma automaticamente a entrada do usuário para corresponder a um formato fornecido. Quando usadas adequadamente, as entradas com máscara podem proporcionar uma experiência de usuário aprimorada, eliminando qualquer ambiguidade para o valor desejado (por exemplo, um número de telefone ou número de segurança social).

Exemplo básico

Máscaras

A máscara é o formato desejado da entrada. Ela é passada para a propriedade mask onde é analisada por tokens. A máscara é composta por:

• Tokens - Uma representação em string de uma região editável pelo usuário. Mostrada em branco abaixo.
• Literais de string - Qualquer caractere que não seja um token. Não editável pelo usuário. Mostrado em laranja abaixo.

Tokens integrados

A entrada com máscara vem com 4 tokens integrados:

• h - Aceita um caractere hexadecimal (0-9a-fA-F).
• # - Aceita um caractere numérico.
• a - Aceita um caractere alfabético.
• * - Aceita qualquer caractere.

Escapando integrados

Se você precisar usar um dos tokens integrados como um literal de string em sua máscara, você pode escapá-los com \. Aqui estamos escapando o sinal de cerquilha # para usar em nossa cor hexadecimal:

<FormKit mask="\#hhhhhh" type="mask" />

Modos

A entrada com máscara suporta 3 modos de entrada:

• Shift (padrão)
• Replace (Substituir)
• Select (Selecionar)

Modo Shift & replace

Por padrão, os caracteres de uma máscara são automaticamente deslocados para frente ao digitar. Isso é notável quando uma máscara já está preenchida e você coloca o cursor no início ou perto do início da entrada e começa a digitar. Os caracteres que seguem o seu cursor são "deslocados" para frente conforme você digita. No modo replace, no entanto, os caracteres subsequentes são sobrescritos com um novo valor:

Modo Select

No modo select, tokens equivalentes do tipo char são agrupados em faixas de texto selecionáveis. O FormKit seleciona automaticamente essas faixas de texto ao clicar ou focar na entrada. Essas faixas de seleção são mantidas enquanto o usuário digita. Quando usado com bom gosto, isso produz uma UX clara, pois o usuário está ciente do valor que se espera que ele insira.

Além disso, quando uma entrada está no modo select, o usuário pode usar as teclas de seta ou tab para mover o foco de uma faixa de seleção para outra:

Tokens

Criando novos tokens

E se um padrão puder aceitar letras ou números na mesma posição? É relativamente simples criar novos tokens. Existem 2 tipos de tokens:

• char aceita um único caractere.
• enum aceita qualquer string de um array de valores possíveis.

As seguintes propriedades devem ser definidas para criar um novo token:

{
  /**
   * O tipo de token. Pode ser `char` ou `enum`.
   */
  type: 'char',
  /**
   * O token a ser extraído da máscara.
   */
  token: 'z',
  /**
   * Um caractere de espaço reservado para exibir na entrada quando `show-mask` está
   * habilitado.
   */
  placeholder: '_',
  /**
   * Ao usar o modo `select`, determina em qual direção os novos caracteres fluem
   * para dentro.
   */
  selectDirection: 'left',
  /**
   * (Somente para o tipo `char`). Uma expressão regular que descreve os tipos de
   * caracteres que podem aparecer neste espaço. Este padrão será avaliado
   * contra caracteres individuais — não no contexto da string inteira.
   */
  pattern: /[A-Za-z0-9]/,
  /**
   * (Somente para o tipo `char`, opcional). Um caractere opcional para "preencher" o
   * intervalo de seleção quando no modo select. Por exemplo, um selectFill definido como
   * "0" pode ser útil com números para produzir zeros à esquerda como "001".
   */
  selectFill: "0",
  /**
   * (Somente para o tipo `enum`). Um array de valores possíveis.
   */
  values: [
    'March',
    'April',
    'May'
  ],
}

Por exemplo, um novo token que aceita letras e números, e é representado pela letra z na string da máscara seria assim:

{
  type: 'char',
  token: 'z',
  pattern: /[A-Za-z0-9]/,
  placeholder: '_',
  selectDirection: 'left',
}

Adicionar tokens via prop

Para passar um novo token para a entrada de máscara, você pode usar a propriedade tokens que espera um objeto com chaves que correspondem à propriedade token. Por exemplo, nosso novo token no exemplo acima pode ser aplicado diretamente:

Adicionar tokens globalmente

Para registrar seus tokens de máscara globalmente, estenda a propriedade config da sua configuração global do FormKit:

Modificar tokens

Além de criar novos tokens, a propriedade tokens também pode modificar tokens existentes. Qualquer valor fornecido para a propriedade tokens será mesclado aos tokens existentes para aquela entrada. Por exemplo, o token de dígito (#) não possui selectFill por padrão. Para adicionar um, basta estendê-lo:

Tokens de caracteres

Tokens char aceitam um único caractere. Para que um caractere seja aceito, ele deve corresponder à expressão regular token.pattern. Os quatro tokens integrados (h, #, a e *) são todos tokens do tipo char.

No modo select, os tokens char são agrupados em um intervalo de seleção.

Tokens Enum

Tokens Enum permitem máscaras de comprimento variável dentro de um conjunto predefinido de opções. À medida que um usuário começa a digitar, o valor do token Enum mudará para o primeiro valor correspondente, e o intervalo de seleção refletirá os caracteres ainda não correspondidos. Na prática, isso funciona muito como um autocompletar para aquele token específico. Além disso, os usuários podem percorrer as opções disponíveis para um determinado token pressionando as teclas de seta para cima/baixo.

Uma data com nomes de meses que se completam automaticamente poderia ser bem representada com enums:

Grupos

Grupos são uma maneira de tratar vários caracteres de máscara como uma única unidade. Você cria um grupo cercando os caracteres de máscara desejados com {}:

<FormKit mask="id{-a#a}" type="mask" />
<!-- "-a#a" é o grupo -->

Por si só, grupos não fazem nada a menos que você defina opções de grupo.

Opções de grupo

Opções de grupo permitem aplicar funcionalidades a um grupo inteiro usando um pipe | seguido pelo nome da opção e quaisquer argumentos. As opções disponíveis são:

• repeat — permite que um grupo seja repetido um número infinito de vezes.
• placeholder — Um caractere para ocupar espaço antes da entrada do usuário.

Parâmetros de opção

Argumentos podem ser passados para uma opção de grupo usando dois pontos, como em placeholder: , onde o símbolo de mais é passado para a opção placeholder.

Você pode encadear opções de grupo:

Prefixo & sufixo

Você pode garantir que certos caracteres sempre apareçam no início ou no final de uma entrada usando as props prefix e suffix, respectivamente:

Executando a máscara ao contrário

Em circunstâncias específicas, você pode querer executar sua máscara ao contrário. A máscara testará se a entrada do usuário preenche a máscara da direita para a esquerda. Isso é comum em entradas do tipo moeda e pode ser aplicado adicionando a prop reverse:

Valores da máscara

Valores incompletos

O valor de uma máscara não é considerado "completo" até que o usuário tenha preenchido todo o padrão. Até esse ponto, o FormKit considerará o valor da entrada "vazio". Isso torna conveniente usar com regras de validação como required. No entanto, se você gostaria de aceitar valores incompletos, você pode fazer isso através da prop allow-incomplete:

Valores sem máscara

Por padrão, o valor de uma entrada de máscara inclui a formatação fornecida através da prop mask. No entanto, se você deseja o valor bruto sem máscara com os literais de string removidos, você pode usar a prop unmask-value:

Ocultando a máscara

Por padrão, a entrada mask exibe o caractere de espaço reservado de cada token. Você pode desativar esse comportamento (exceto no modo select) enquanto ainda aplica a formatação automaticamente através da prop show-mask:

Sobreposição (colorindo uma máscara)

Por padrão, o valor de uma máscara é exibido através do valor do seu elemento de entrada. Embora isso funcione "pronto para uso", não permite que o texto seja diferenciado estilisticamente. Por exemplo, seria bom se as partes "literais" da máscara parecessem diferentes das partes "placeholder".

Para alcançar esse efeito, você pode habilitar uma sobreposição que renderiza elementos DOM posicionados diretamente sobre a própria entrada. O texto dentro da entrada ainda está lá, mas será transparente. Em geral, os estilos de posicionamento necessários para a sobreposição são aplicados automaticamente para você.

A sobreposição contém 4 seções possíveis nas quais você pode direcionar seus estilos:

• Literal (.formkit-overlay-literal ou overlay-literal-class)
• Placeholder (.formkit-overlay-placeholder ou overlay-placeholder-class)
• Enum (.formkit-overlay-enum ou overlay-enum-class)
• Char (.formkit-overlay-char ou overlay-char-class)

O tema padrão genesis suporta automaticamente a sobreposição e aplica cores cinza claro ao placeholder. Se você não estiver usando o Genesis, certifique-se de que a seção inner esteja posicionada (como position: relative).

Props & Atributos

Seções

Você pode direcionar uma seção específica de uma entrada usando a "key" dessa seção, permitindo que você modifique as classes, HTML (por meio de :sections-schema ou o conteúdo (por meio de slots) dessa seção). Saiba mais sobre as seções aqui.

Acessibilidade

Todos os campos de entrada do FormKit são projetados levando em consideração as seguintes considerações de acessibilidade. Ajude-nos a melhorar continuamente a acessibilidade para todos, relatando problemas de acessibilidade aqui:

Interações com o Teclado