Mask

• Introduction
• Exemple de base
• Masques
  • Tokens intégrés
  • Échapper aux intégrés
• Modes
  • Mode Shift & remplacer
  • Mode Sélectionner
• Jetons
  • Création de nouveaux jetons
  • Modifier les jetons
  • Jetons Char
  • Jetons Enum
• Groupes
  • Options de groupe
• Préfixe & suffixe
• Exécution du masque à l'envers
• Valeurs de masque
  • Valeurs incomplètes
  • Valeurs non masquées
• Masquer le masque
• Superposition (coloration d'un masque)
• Props & Attributs
• Sections

Introduction

L'entrée masque transforme automatiquement l'entrée de l'utilisateur pour correspondre à un format fourni. Utilisées de manière appropriée, les entrées masquées peuvent améliorer l'expérience utilisateur en éliminant toute ambiguïté sur 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 passé à la propriété masque où il est analysé pour les tokens. Le masque est composé de :

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

Tokens intégrés

L'entrée de masque est livrée avec 4 tokens 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 aux intégrés

Si vous avez besoin d'utiliser l'un des tokens 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 hex :

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

Modes

L'entrée de masque supporte 3 modes d'entrée :

• Shift (par défaut)
• Remplacer
• Sélectionner

Mode Shift & remplacer

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à peuplé 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 lorsque vous tapez. En mode remplacer, cependant, les caractères suivants sont écrasés par une nouvelle valeur :

Mode Sélectionner

En mode sélection, les tokens de type char équivalents sont regroupés en plages de texte sélectionnables. FormKit sélectionne automatiquement ces plages de texte lors du clic ou de la mise au point de l'entrée. Ces plages de sélection sont maintenues pendant que l'utilisateur tape. Lorsqu'il est 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 sélection, l'utilisateur peut utiliser les touches flèche ou tabulation 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 de caractères parmi 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 `enum`.
   */
  type: 'char',
  /**
   * Le jeton à analyser à partir 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 s'écoulent
   * dans.
   */
  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é
   * contre des caractères individuels - pas dans le contexte de la chaîne entière.
   */
  pattern: /[A-Za-z0-9]/,
  /**
   * (Uniquement pour le type `char`, facultatif). Un caractère facultatif pour "remplir" le
   * plage de sélection avec lorsqu'il est en mode sélection. Par exemple, un selectFill défini sur
   * "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 les lettres et les 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 prop

Pour passer un nouveau jeton à l'entrée du masque, vous pouvez utiliser la prop 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 de chiffre (#) n'a pas de selectFill par défaut. Pour en ajouter un, il suffit de l'étendre :

Jetons Char

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 en une plage de sélection.

Jetons Enum

Les jetons Enum permettent des masques de longueur variable dans 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 correspondants. En pratique, cela fonctionne un peu comme une auto-complé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 en auto-complétion pourrait être bien représentée avec des énumérations :

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 par {} :

<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 tous les arguments. Les options disponibles sont :

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

Paramètres d'option

Les arguments peuvent être passés à une option de groupe en utilisant un 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 les props prefix et suffix, respectivement :

Exécution du masque à l'envers

Dans des circonstances spécifiques, vous pouvez vouloir exécuter votre masque à l'envers. Le masque vérifiera si l'entrée de l'utilisateur remplit le masque de droite à gauche. Ceci est courant dans les entrées de type monétaire et peut être appliqué en ajoutant la prop reverse :

Valeurs de masque

Valeurs incomplètes

La valeur d'un 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 le rend pratique à utiliser avec des règles de validation comme required. Cependant, si vous souhaitez accepter des valeurs incomplètes, vous pouvez le faire via la prop allow-incomplete :

Valeurs non masquées

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

Masquer le masque

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

Superposition (coloration 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 "out of the box", cela ne permet pas de différencier stylistiquement le texte. Par exemple, il serait agréable que les parties "littérales" du masque aient un aspect différent des parties "placeholder".

Pour obtenir cet effet, vous pouvez activer une superposition qui rend des éléments DOM qui sont positionnés directement sur 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 de superposition nécessaires 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 au placeholder. 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.