Passer au contenu principal

DateField

Ouvrir dans ChatGPT
Shadow dwc-field 23.02
Java API

Le composant DateField permet aux utilisateurs d'entrer ou de sélectionner une date par année, mois et jour. Il gère automatiquement la validation, de sorte que les dates mal formatées sont détectées avant que le formulaire soit soumis.

Utilisation de DateField​

Inheritance

This class is a Field component, and inherits its features and behaviors. For an overview of Field properties, events, and other important information, please refer to the Field documentation.

DateField étend la classe partagée Field, qui fournit des fonctionnalités communes à tous les composants de champ. L'exemple suivant crée des DateFields de départ et de retour qui restent synchronisés, avec des contraintes min et max pour limiter la plage sélectionnable.

Afficher le code

Valeur de champ (LocalDate)​

Le composant DateField stocke sa valeur en interne comme un objet LocalDate, représentant une date sans information sur l'heure ou le fuseau horaire. Cela permet de gérer correctement les entrées basées sur le calendrier à travers différents systèmes.

Valeur affichée VS valeur analysée

Tandis que la valeur affichée s'adapte à la locale du navigateur de l'utilisateur, garantissant un formatage familier régionalement (par exemple, MM/JJ/AAAA aux États-Unis ou JJ.MM.AAAA en Europe), la valeur analysée repose toujours sur le format fixe de aaaa-MM-jj.

Obtention et définition de la valeur LocalDate​

Pour récupérer la valeur actuelle, utilisez la méthode getValue() :

LocalDate value = dateField.getValue();

Pour définir la valeur de manière programmatique, utilisez la méthode setValue() :

dateField.setValue(LocalDate.of(2024, 4, 27));

Utilisation de setText()​

Vous pouvez également attribuer une valeur en utilisant une chaîne brute, mais elle doit suivre le format exact aaaa-MM-jj :

dateField.setText("2024-04-27"); // valide

dateField.setText("04/27/2024"); // invalide
avertissement

Lors de l'utilisation de la méthode setText(), une IllegalArgumentException sera levée si le composant ne peut pas analyser l'entrée dans le format aaaa-MM-jj.

Utilisations​

Le DateField est idéal pour choisir et afficher des dates dans votre application. Voici quelques exemples de quand utiliser le DateField :

  1. Planification d'événements et calendriers : Les champs de date sont essentiels dans les applications qui impliquent la planification d'événements, la réservation de rendez-vous ou le suivi de dates importantes.

  2. Entrées de formulaire : Simplifiez le processus de sélection de dates pour un utilisateur remplissant un formulaire qui nécessite une date, comme un anniversaire.

  3. Systèmes de réservation et de réservation : Les applications impliquant des systèmes de réservation nécessitent souvent que les utilisateurs saisissent des dates spécifiques. Un champ de date simplifie le processus et garantit une sélection de date précise.

  4. Gestion des tâches et délais : Les champs de date sont précieux dans les applications qui impliquent la gestion des tâches ou la définition de délais. Les utilisateurs peuvent facilement spécifier des dates d'échéance, des dates de début ou d'autres informations sensibles au temps.

Valeur min et max​

La valeur min​

La méthode setMin() définit la date la plus ancienne qu'un utilisateur peut saisir dans le composant. Si l'entrée est antérieure à la minimum spécifiée, elle échouera à la validation des contraintes. Lorsqu'elle est utilisée conjointement avec setMax(), la minimum doit être une date qui est la même ou antérieure à la maximum.

dateField.setMin(LocalDate.of(2023, 1, 1)); // Minimum autorisé : 1er janvier 2023

La valeur max​

La méthode setMax() définit la date la plus récente que le composant accepte. Si la date saisie est postérieure à la maximum spécifiée, l'entrée est invalide. Lorsque les deux valeurs sont définies, la maximum doit être une date qui est la même ou postérieure à la minimum.

dateField.setMax(LocalDate.of(2023, 12, 31)); // Maximum autorisé : 31 décembre 2023

Utilitaires statiques​

La classe DateField fournit également les méthodes utilitaires statiques suivantes :

  • fromDate(String dateAsString): Convertit une chaîne de date au format aaaa-MM-jj en un objet LocalDate qui peut ensuite être utilisé avec ce champ, ou ailleurs.

  • toDate(LocalDate date): Convertit un objet LocalDate en une chaîne de date au format aaaa-MM-jj.

  • isValidDate(String dateAsString): Vérifie si la chaîne donnée est une date valide au format aaaa-MM-jj.

Meilleures pratiques​

Pour assurer une expérience utilisateur optimale lors de l'utilisation du composant DateField, considérez les meilleures pratiques suivantes :

  • Accessibilité : Utilisez des labels appropriés pour garantir que les utilisateurs avec des technologies d'assistance peuvent facilement naviguer et utiliser les champs de date dans votre application.

  • Auto-compléter la date actuelle : Si c'est approprié pour le cas d'utilisation de votre application, auto-complétez le champ de date avec la date actuelle.