Mask

• Introduction
• Exemple de base
• Masques
  • Jetons intégrés
  • Échapper les intégrés
• Modes
  • Mode Shift & Replace
  • Mode Select
• Jetons
  • Création de nouveaux jetons
  • Modifier les jetons
  • Jetons de caractères
  • Jetons Enum
• Groupes
  • Options de groupe
• Préfixe & suffixe
• Exécuter le masque à l'envers
• Valeurs du masque
  • Valeurs incomplètes
  • Valeurs non masquées
• Masquer le masque
• Superposition (colorisation d'un masque)
• Props & Attributs
• Sections
• Accessibilité
  • Interactions Clavier

Introduction

L'entrée mask transforme automatiquement la saisie de l'utilisateur pour correspondre à un format fourni. Utilisées correctement, les entrées de masque peuvent offrir une meilleure expérience utilisateur en éliminant toute ambiguïté pour la valeur souhaitée (par exemple un numéro de téléphone ou un numéro de sécurité sociale).

Exemple de base

Masques

Le masque est le format souhaité de l'entrée. Il est transmis à la propriété mask où il est analysé pour les jetons. Le masque est composé de :

• Jetons - Une représentation en chaîne de caractères d'une région modifiable par l'utilisateur. Affichée en blanc ci-dessous.
• Littéraux de chaîne - Tout caractère qui n'est pas un jeton. Non modifiable par l'utilisateur. Affiché en orange ci-dessous.

Jetons intégrés

L'entrée de masque est livrée avec 4 jetons intégrés :

• h - Accepte un caractère hexadécimal (0-9a-fA-F).
• # - Accepte un caractère numérique.
• a - Accepte un caractère alphabétique.
• * - Accepte n'importe quel caractère.

Échapper les intégrés

Si vous avez besoin d'utiliser l'un des jetons intégrés comme un littéral de chaîne dans votre masque, vous pouvez les échapper avec \. Ici, nous échappons le signe dièse # pour l'utiliser dans notre couleur hexadécimale :

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

Modes

L'entrée de masque prend en charge 3 modes de saisie :

• Shift (par défaut)
• Replace
• Select

Mode Shift & Replace

Par défaut, les caractères d'un masque sont automatiquement décalés vers l'avant lors de la frappe. Cela est notable lorsqu'un masque est déjà rempli et que vous placez le curseur au début ou près du début de l'entrée et commencez à taper. Les caractères suivant votre curseur sont "décalés" vers l'avant au fur et à mesure que vous tapez. Cependant, en mode replace, les caractères suivants sont écrasés par une nouvelle valeur :

Mode Select

En mode select, les jetons de type char équivalents sont regroupés en plages de texte sélectionnables. FormKit sélectionne automatiquement ces plages de texte lors d'un clic ou d'une mise au point sur l'entrée. Ces plages de sélection sont maintenues pendant que l'utilisateur tape. Utilisé avec goût, cela produit une UX claire car l'utilisateur est conscient de la valeur qu'il est censé entrer.

De plus, lorsqu'une entrée est en mode select, l'utilisateur peut utiliser les touches fléchées ou tab pour déplacer son focus d'une plage de sélection à une autre :

Jetons

Création de nouveaux jetons

Que se passe-t-il si un motif peut accepter des lettres ou des chiffres à la même position ? Il est relativement simple de créer de nouveaux jetons. Il existe 2 types de jetons :

• char accepte un seul caractère.
• enum accepte n'importe quelle chaîne d'un tableau de valeurs possibles.

Les propriétés suivantes doivent être définies pour créer un nouveau jeton :

{
  /**
   * Le type de jeton. Peut être un `char` ou un `enum`.
   */
  type: 'char',
  /**
   * Le jeton à extraire du masque.
   */
  token: 'z',
  /**
   * Un caractère de remplacement à afficher dans l'entrée lorsque `show-mask` est
   * activé.
   */
  placeholder: '_',
  /**
   * Lors de l'utilisation du mode `select`, détermine dans quelle direction les nouveaux caractères
   * sont insérés.
   */
  selectDirection: 'left',
  /**
   * (Uniquement pour le type `char`). Une expression régulière qui décrit les types de
   * caractères qui peuvent apparaître dans cet emplacement. Ce motif sera évalué
   * sur des caractères individuels — et non dans le contexte de la chaîne entière.
   */
  pattern: /[A-Za-z0-9]/,
  /**
   * (Uniquement pour le type `char`, optionnel). Un caractère optionnel pour "remplir" la
   * plage de sélection en mode select. Par exemple, un selectFill défini à
   * "0" peut être utile avec des chiffres pour produire des zéros non significatifs comme "001".
   */
  selectFill: "0",
  /**
   * (Uniquement pour le type `enum`). Un tableau de valeurs possibles.
   */
  values: [
    'Mars',
    'Avril',
    'Mai'
  ],
}

Par exemple, un nouveau jeton qui accepte des lettres et des chiffres, et qui est représenté par la lettre z dans la chaîne de masque ressemblerait à ceci :

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

Ajouter des jetons via la prop

Pour passer un nouveau jeton à l'entrée de masque, vous pouvez utiliser la propriété tokens qui attend un objet avec des clés qui correspondent à la propriété token. Par exemple, notre nouveau jeton dans l'exemple ci-dessus peut être appliqué directement :

Ajouter des jetons globalement

Pour enregistrer vos jetons de masque globalement, étendez la propriété config de votre configuration globale FormKit :

Modifier les jetons

En plus de créer de nouveaux jetons, la propriété tokens peut également modifier les jetons existants. Toute valeur fournie à la propriété tokens sera fusionnée avec les jetons existants pour cette entrée. Par exemple, le jeton chiffre (#) n'a pas de selectFill par défaut. Pour en ajouter un, il suffit de l'étendre :

Jetons de caractères

Les jetons char acceptent un seul caractère. Pour qu'un caractère soit accepté, il doit correspondre à l'expression régulière token.pattern. Les quatre jetons intégrés (h, #, a et *) sont tous des jetons de type char.

En mode select, les jetons char sont regroupés ensemble dans une plage de sélection.

Jetons Enum

Les jetons Enum permettent des masques de longueur variable au sein d'un ensemble prédéfini d'options. Lorsqu'un utilisateur commence à taper, la valeur du jeton Enum changera pour la première valeur correspondante, et la plage de sélection reflétera les caractères actuellement non appariés. En pratique, cela fonctionne un peu comme une autocomplétion pour ce jeton spécifique. De plus, les utilisateurs peuvent parcourir les options disponibles pour un jeton donné en appuyant sur les touches fléchées haut/bas.

Une date avec des noms de mois à autocomplétion pourrait être bien représentée avec des enums :

Groupes

Les groupes sont un moyen de traiter plusieurs caractères de masque comme une seule unité. Vous créez un groupe en entourant les caractères de masque souhaités de {} :

<FormKit mask="id{-a#a}" type="mask" />
<!-- "-a#a" est le groupe -->

Par eux-mêmes, les groupes ne font rien à moins que vous ne définissiez des options de groupe.

Options de groupe

Les options de groupe vous permettent d'appliquer une fonctionnalité à un groupe entier en utilisant un pipe | suivi du nom de l'option et de ses arguments. Les options disponibles sont :

• repeat — permet à un groupe d'être répété un nombre infini de fois.
• placeholder — Un caractère pour tenir l'espace avant la saisie de l'utilisateur.

Paramètres d'option

Des arguments peuvent être passés à une option de groupe en utilisant deux-points, comme placeholder:+, où le symbole plus + est passé à l'option placeholder.

Vous pouvez enchaîner les options de groupe :

Préfixe & suffixe

Vous pouvez vous assurer que certains caractères apparaissent toujours au début ou à la fin d'une entrée en utilisant respectivement les propriétés prefix et suffix :

Exécuter le masque à l'envers

Dans certaines circonstances, vous pouvez vouloir exécuter votre masque à l'envers. Le masque testera si l'entrée de l'utilisateur remplit le masque de droite à gauche. Cela est courant dans les entrées de type monétaire et peut être appliqué en ajoutant la propriété reverse :

Valeurs du masque

Valeurs incomplètes

Une valeur de masque n'est pas considérée comme "complète" tant que l'utilisateur n'a pas rempli l'ensemble du motif. Jusqu'à ce point, FormKit considérera la valeur de l'entrée comme "vide". Cela rend son utilisation pratique avec des règles de validation comme required. Cependant, si vous souhaitez accepter des valeurs incomplètes, vous pouvez le faire via la propriété allow-incomplete :

Valeurs non masquées

Par défaut, la valeur d'une entrée masquée inclut le formatage fourni via la propriété mask. Cependant, si vous souhaitez la valeur brute non masquée avec les littéraux de chaîne supprimés, vous pouvez utiliser la propriété unmask-value :

Masquer le masque

Par défaut, l'entrée mask affiche le caractère de placeholder de chaque jeton. Vous pouvez désactiver ce comportement (sauf en mode sélection) tout en appliquant automatiquement le formatage via la propriété show-mask :

Superposition (colorisation d'un masque)

Par défaut, la valeur d'un masque est affichée via la valeur de son élément d'entrée. Bien que cela fonctionne "tel quel", cela ne permet pas de différencier stylistiquement le texte. Par exemple, il serait agréable que les parties "littérales" du masque aient une apparence différente des parties "placeholders".

Pour obtenir cet effet, vous pouvez activer une superposition qui rend des éléments DOM positionnés directement au-dessus de l'entrée elle-même. Le texte à l'intérieur de l'entrée est toujours là, mais il sera transparent. En général, les styles de positionnement nécessaires pour la superposition sont automatiquement appliqués pour vous.

La superposition contient 4 sections possibles sur lesquelles vous pouvez cibler vos styles :

• Littéral (.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)

Le thème genesis par défaut prend automatiquement en charge la superposition et applique des couleurs gris clair aux placeholders. Si vous n'utilisez pas Genesis, veuillez vous assurer que la section inner est positionnée (comme position: relative).

Props & Attributs

Sections

Vous pouvez cibler une section spécifique d'une entrée en utilisant la "key" de cette section, ce qui vous permet de modifier les classes de cette section, le HTML (via :sections-schema) ou le contenu (via des emplacements)). En savoir plus sur les sections ici.

Accessibilité

Tous les champs de saisie FormKit sont conçus en tenant compte des considérations d'accessibilité suivantes. Aidez-nous à améliorer continuellement l'accessibilité pour tous en signalant les problèmes d'accessibilité ici:

Interactions Clavier