Note: Il existe des versions obsolètes de ce composant. Passez à une version de la documentation antérieure à la version 10.3.x pour consulter cette documentation.
Utilisation
Présentation
Un masque de saisie guide les utilisateurs dans la saisie de données en contraignant et en mettant en forme les informations dans un format spécifique au fur et à mesure de leur saisie.
Vous pouvez appliquer un masque au champ de saisie de texte et au champ de saisie du numéro de téléphone.
Quand l'utiliser
Dans les champs dont le format attendu est spécifique, par exemple Numéro de sécurité sociale ou Code postal.
Quand ne pas l'utiliser
- Pour une saisie qui nécessite un champ de forme libre.
- Lorsque le modèle de saisie est trop complexe pour un masque. Par exemple, une adresse e-mail peut être saisie dans de nombreux scénarios.
Structure
Example du champ de saisie de numéro de téléphone avec un masque de saisie.
- Étiquette : décrit l'objectif d'un champ de saisie.
- Masque de saisie : expression de chaîne qui contraint la saisie à prendre en charge les valeurs de saisie valides. Le masque de saisie apparaît lorsque le focus lui est appliqué.
- Champ de saisie du numéro de téléphone : champ amélioré qui permet aux utilisateurs d'entrer leur numéro de téléphone. Il n'accepte que des entrées numériques et est automatiquement formaté.
Contenu
Pour les normes de contenu, reportez-vous aux règles de rédaction propres à la saisie de texte et à la saisie de numéro de téléphone.
Comportements
Le masque de saisie apparaît dès que le focus lui est appliqué. Avant le focus, le champ de saisie est vide ou affiche le texte de l'espace réservé.
Exemple de champ de saisie de texte activé (à gauche) et de champ de saisie de texte ciblé (à droite).
Accessibilité
Ce composant a été validé pour répondre aux directives d’accessibilité WCAG 2.2 AA dans sa configuration de base par défaut. Il s’agit notamment de s’assurer que :
- Le rapport de contraste des éléments textuels par rapport à leur arrière-plan est supérieur à 4.5:1.
- Le contenu non textuel qui doit transmettre le sens (comme les icônes et les indicateurs de focus) a un rapport de contraste d’au moins 3:1 avec ses couleurs adjacentes.
- Cet élément peut être utilisé à l’aide d’un clavier et d’une souris.
- Le contenu est accessible à l’aide de lecteurs d’écran, tels que JAWS et VoiceOver.
La conformité de l’accessibilité dépend en définitive de la façon dont ce composant est implémenté et personnalisé. Les modifications apportées par l’auteur du contenu peuvent affecter l’accessibilité. Pour en savoir plus sur notre modèle de responsabilité partagée, consultez notre Déclaration d’accessibilité Jutro complète.
Lorsque vous utilisez ce composant dans votre application, assurez-vous que les étiquettes et les instructions sont pertinentes et concises. Fournissez des instructions supplémentaires si nécessaire.
Note: Il existe des versions obsolètes de ce composant. Passez à une version de la documentation antérieure à la version 10.3.x pour consulter cette documentation.
Code
Instruction d'importation
import { MaskInput } from '@jutro/components';
Cahier des charges du composant
Assurez-vous de comprendre la surface de l'API des composants du système de conception, ainsi que les implications et les compromis. Pour en savoir plus, reportez-vous à notre introduction à l'API des composants.
Propriétés
labelobligatoire
DescriptionLabel associated with input field, also passed as a default value to aria-label.
maskobligatoire
DescriptionString that formats the mask to display, for example 999-999-9999. It defines the structure of the input value, where each character represents a different type of input. For example, 9 represents a numeric character, A represents an alphabetical character, and * represents an alphanumeric character. It also defines the position of static characters, such as dashes or parentheses, and the overall input length. The component follows a fixed-length pattern, hence mask property does not allow optional characters.
className
DescriptionCSS class name for this component.
disabled
DescriptionIf set to true, component is rendered in disabled state.
displayOnly
DescriptionIf set to true, displays the component value in plain text. Consider using readonly instead, if possible, because plain text is worse for accessibility than readonly inputs.
DescriptionA map of special mask formatting characters and the corresponding regular expressions the input must satisfy.
Valeur par défaut{9: '[0-9]', a: '[A-Za-z]', A: '[A-Z]', '*': '[A-Za-z0-9]', '&': '[0-9A-Z]'}
hideLabel
DescriptionIf set to true, the label is not visible.
initialValue
DescriptionInitial value of input. If the value property is specified along with this property, this property's value is discarded.
labelPosition
DescriptionAllows to select label position.
onBlur
Typefunction (FocusEvent<HTMLInputElement>)
DescriptionA callback called after the component is focused.
onChange
Typefunction (React.ChangeEvent<HTMLInputElement>, string)
DescriptionCallback invoked when component value is changed.
onFocus
Typefunction (FocusEvent<HTMLInputElement>)
DescriptionA callback called after the component is focused.
placeholder
DescriptionPlaceholder to display on an empty component.
readOnly
DescriptionIf set to true, component is rendered in a read-only state. For values in plain text, consider using displayOnly.
required
DescriptionIf set to true, sets the field as required displaying an asterisk.
secondaryLabel
DescriptionSecondary label text to display.
stateMessages
DescriptionAn object with a list of error messages for the current state.
Type{ text: intlMessageShape, trigger: string } | intlMessageShapetext
DescriptionText to show tooltip content.
trigger
DescriptionThe trigger to show the tooltip.
DescriptionText to be displayed in the tooltip or tooltip object that includes: text - to show tooltip content, trigger - to set tooltip trigger.
value
DescriptionValue of input. Takes precedence over initialValue. If this property is passed, component works in controlled mode and its value changes only if this property changes.
Crochets
Aucun crochet n'est disponible pour MaskInput.
Clés de traduction
Aucune clé de traduction n'est associée au composant MaskInput.
Portes de sortie
Pour en savoir plus, reportez-vous à notre documentation sur les portes de sortie.
Les options suivantes sont disponibles :
- Jetons de conception
- Propriété
className
- Transmission d'attributs HTML natifs
- Référence avec gestionnaires impératifs
- Propriété d'événement natif
Comportements personnalisés
Valeur masquée et non masquée
Lors de la saisie d'une valeur dans MaskInput, elle est automatiquement formatée et la valeur formatée est présentée comme un deuxième argument dans l'événement onChange. Si vous devez accéder à la valeur non formatée, le composant MaskInput étend l'événement onChange pour inclure un troisième paramètre. Ce paramètre est un objet qui contient la propriété non masquée intégrant la valeur non formatée.
Un champ MaskInput vide sur lequel le focus n'est pas appliqué n'affiche rien ou contient un espace réservé donné s'il est défini par défaut. Lors de l'application du focus au champ, le masque devient visible. Les utilisateurs peuvent saisir des valeurs correspondant au masque, ce qui rend le masque invisible. Si la valeur fournie contient moins de caractères que ce qui est indiqué par le masque, la saisie est ignorée. Les masques partiellement remplis conservent la valeur fournie et ajoutent les caractères du masque restants, même lorsque le focus n'est plus appliqué au champ. Dans les modes readOnly et displayOnly, le masque reste masqué quel que soit l'état de la saisie. En mode disabled, le masque reste visible comme en mode enabled.
Copier et coller
Lorsqu'une valeur est collée dans le champ, elle est formatée pour correspondre au masque spécifié. Si MaskInput détecte un caractère qui ne correspond pas aux exigences du masque, par exemple coller des lettres alors que le masque attend des chiffres, le caractère qui ne correspond pas et le reste de la valeur sont ignorés. En outre, si la valeur fournie dépasse la longueur spécifiée par le masque, la valeur est tronquée pour correspondre à la longueur du masque.
Précédence Disabled, displayOnly et readOnly
Si au moins deux des propriétés disabled, displayOnly, et readOnly sont définies sur true en même temps, l'ordre de préséance suivant s'applique :
displayOnly > readOnly > disabled
Bien que certains composants de Jutro puissent fournir des fonctionnalités complémentaires ou une fonction d'aide pour faciliter le processus de validation, il vous appartient, en tant que développeur, de gérer la validation de toute entrée utilisateur (en utilisant ou non les fonctions d'aide complémentaires) et de déterminer les messages d'erreur à afficher.
Le comportement des composants Jutro est basé sur l'implémentation du développeur.
Quand est-ce que des messages d'erreur s'affichent ?
Les messages d'erreur ne s'affichent que lorsque vous les transmettez au composant via la propriété stateMessages. Cette propriété reçoit un objet avec le contenu suivant :
{
error: ['error message 1', 'error message 2', 'error message N'];
}
Le composant affiche chaque message d'erreur fourni dans le même ordre que dans la série.
Quand la validation a-t-elle lieu ?
Cette décision vous revient en tant que développeur. Étant donné que les composants ne déterminent pas le moment où la validation est effectuée ou le moment où l'erreur doit être affichée, vous devez implémenter la logique pour la traiter en fonction des exigences du projet, par exemple lorsque l'utilisateur modifie le contenu, lorsque le composant active une autre fenêtre et lors de la soumission du formulaire.
Utilisez-vous un composant InputMaskField existant ?
- Pour consulter la documentation des anciens composants, passez à une version de la documentation antérieure à 10.3.
- Ce composant existant est également disponible dans Storybook :
Note: Il existe des versions obsolètes de ce composant. Passez à une version de la documentation antérieure à la version 10.3.x pour consulter cette documentation.
Exemples
import React from 'react';
import { MaskInput } from '@jutro/components';
export const BasicMaskinput = () => {
return (
<MaskInput
label="Mask input component"
mask="(999) 999-9999"
secondaryLabel="This is a secondary label"
initialValue="(123) 942-4237"
/>
);
};
Note: Si initialValue est défini et ne correspond pas au masque, cette valeur est ignorée
Vous pouvez créer un mappage personnalisé des caractères de formatage et des expressions régulières correspondantes que la saisie doit respecter. Dans cet exemple, le masque DDD représente n'importe quelle lettre de A à Z en majuscules et 0000 représente un nombre quelconque compris entre 0 et 5.
import React, { useState } from 'react';
import { TextInput, MaskInput } from '@jutro/components';
export const FormatCharsMaskInput = () => {
const [value, setValue] = useState('');
const formatChars = {
D: '[A-Z]',
0: '[0-5]',
};
return (
<div>
<MaskInput
label="Enter 3 letters in upper case"
mask="DDD-0000"
formatChars={formatChars}
/>
</div>
);
};
Vous pouvez utiliser la propriété « value » pour le scénario de composant contrôlé :
import React, { useState } from 'react';
import { TextInput, MaskInput } from '@jutro/components';
export const ControlledMaskInput = () => {
const [enteredValue, setEnteredValue] = useState('');
const onChangefunc = (event) => {
const newValue = event.target.value;
setEnteredValue(newValue);
console.log('Entered value:', newValue);
};
return (
<div>
<MaskInput
label="Enter a number to be assigned to the following field"
mask="(999) 999-9999"
onChange={onChangefunc}
stateMessages={{}}
required
/>
<TextInput
label="The value is updated when the first field is modified"
value={enteredValue}
/>
</div>
);
};
Validation
Vous pouvez valider la saisie lorsque le champ est modifié ou lorsqu'il perd le focus à l'aide des propriétés onChange et onBlur, respectivement. En outre, dans cet exemple, la propriété « required » définit le champ comme obligatoire.
import React, { useState } from 'react';
import { TextInput, MaskInput } from '@jutro/components';
export const ValidationMaskInput = () => {
const [enteredValue, setEnteredValue] = useState('');
const onBlurfunc = (event) => {
const newValue = event.target.value;
setEnteredValue(newValue);
};
return (
<div>
<MaskInput
label="Validation onBlur example"
mask="(999) 999-9999"
onBlur={onBlurfunc}
stateMessages={{}}
required
/>
<TextInput
label="The value is updated when the first field loses its focus"
value={enteredValue}
/>
</div>
);
};
Message d'erreur
Permet de définir un message d'erreur personnalisé.
import React from 'react';
import { MaskInput } from '@jutro/components';
export const ErrorMaskInput = () => {
return (
<MaskInput
label="Error field"
mask="(999) 999-9999"
stateMessages={{
error: ['This is a custom error message'],
}}
/>
);
};
Journal des modifications
10.13.0
Un chemin d’importation à partir de @jutro/components a été ajouté pour le composant MaskInput.
L’ancien chemin d’importation à partir de @jutro/components/new sera supprimé dans une prochaine version majeure.
Il est conseillé aux utilisateurs d’exécuter la commande suivante pour appliquer un codemod afin de mettre à jour les chemins d’importation dans votre code.
jutro codemod:apply --name=MigrateMaskInputImportFromNew
Pour en savoir plus sur les codemods Jutro, reportez-vous à la documentation sur les codemods.
10.3.0
Un nouveau composant @jutro/components/new/MaskInput a été introduit pour remplacer InputMaskField.
Le précédent composant lié au masque InputMaskField est obsolète et a été déplacé vers le package @jutro/legacy. Pour afficher la documentation correspondante, passez à une version antérieure.
Emplacement des composants d’origine :
InputMaskField : @jutro/components/InputMaskField
Emplacement des composants mis à jour :
InputMaskField : @jutro/legacy/components/InputMaskField