Aller au contenu principal

DateTimeField

Ouvrir dans ChatGPT
Shadow dwc-field 23.02
Java API
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.

Le composant DateTimeField est conçu pour permettre aux utilisateurs de saisir à la fois une date et une heure. Cela inclut la spécification de l'année, du mois et du jour, ainsi que l'heure en heures et minutes. Il offre aux utilisateurs la possibilité de valider leur saisie pour en vérifier l'exactitude ou d'utiliser une interface de sélection de date-heure dédiée pour simplifier le processus de sélection.

Afficher le code

Usages

Le DateTimeField est préférable dans les scénarios où la capture ou l'affichage à la fois de la date et de l'heure est essentiel pour votre application. Voici quelques exemples de quand utiliser le DateTimeField :

  1. Planification d'événements et calendriers : Permettez aux utilisateurs de planifier efficacement des événements, de réserver des rendez-vous et de gérer leurs calendriers en leur offrant un seul composant qui leur permet de choisir la date et l'heure.
  1. Enregistrement et départ : Facilitez la sélection par l'utilisateur des horaires d'enregistrement et de départ lorsque la période peut s'étendre sur plusieurs jours.
  1. Journalisation des données et horodatages : Utilisez les DateTimeFields pour des applications qui impliquent l'enregistrement de la date et de l'heure auxquelles les événements se produisent ou lorsqu'un utilisateur soumet des données.

  2. Gestion des tâches et délais : Les DateTimeFields sont précieux dans les applications qui impliquent la gestion des tâches ou la définition de délais où à la fois la date et l'heure sont pertinentes pour une planification précise.

Champ de valeur (LocalDateTime)

En interne, le composant DateTimeField représente sa valeur à l'aide d'un objet LocalDateTime du package java.time. Cela fournit un contrôle précis sur les composants de date et d'heure de la saisie.

Bien que la valeur côté client soit rendue en fonction de la locale du navigateur de l'utilisateur (par exemple, les formats de date et d'heure qui correspondent aux conventions locales), la valeur analysée suit une structure stricte et prévisible : yyyy-MM-ddTHH:mm:ss.

Récupération et définition de la valeur

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

LocalDateTime value = dateTimeField.getValue();

Pour définir programmétiquement la valeur, utilisez la méthode setValue() :

dateTimeField.setValue(LocalDateTime.of(2024, 4, 27, 14, 30, 0));

Utilisation de setText()

Si vous préférez définir la valeur via une chaîne brute, elle doit suivre exactement le format yyyy-MM-ddTHH:mm:ss.

dateTimeField.setText("2024-04-27T14:30:00"); // valide

dateTimeField.setText("24-04-27T14:30:00"); // invalide
attention

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 yyyy-MM-ddTHH:mm:ss.

Utilitaires statiques

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

  • fromDateTime(String dateTimeAsString) : Convertit une chaîne de date et heure au format yyyy-MM-ddTHH:mm:ss en un objet LocalDateTime qui peut ensuite être utilisé avec cette classe, ou ailleurs.

  • toDateTime(LocalDateTime dateTime) : Convertit un objet LocalDateTime en une chaîne de date et heure au format yyyy-MM-ddTHH:mm:ss.

  • isValidDateTime(String dateTimeAsString) : Vérifie si la chaîne donnée est une date et une heure valide au format yyyy-MM-ddTHH:mm:ss. Cela renverra une valeur booléenne vraie si c'est le cas, fausse sinon.

Valeur min et max

La valeur min

Si la valeur saisie dans le composant est antérieure à l'horodatage minimum spécifié, le composant échouera à la validation des contraintes. Lorsque les valeurs min et max sont toutes deux définies, la valeur min doit être un horodatage identique ou antérieur à la valeur max.

// Définir l'horodatage minimum autorisé : 1er janvier 2023 à 08:00
dateTimeField.setMin(LocalDateTime.of(2023, 1, 1, 8, 0));

La valeur max

Si la valeur saisie dans le composant est postérieure à l'horodatage maximum spécifié, le composant échouera à la validation des contraintes. Lorsque les valeurs min et max sont toutes deux définies, la valeur max doit être un horodatage identique ou postérieur à la valeur min.

// Définir l'horodatage maximum autorisé : 31 décembre 2023 à 18:00
dateTimeField.setMax(LocalDateTime.of(2023, 12, 31, 18, 0));

Meilleures pratiques

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

  • Affichage de date localisé : La localisation du format de date et l'incorporation des préférences régionales garantissent que les dates sont présentées dans un format familier à l'utilisateur.

  • Inclure des fuseaux horaires : Si votre application traite des informations sensibles au temps à travers différents fuseaux horaires, envisagez d'incorporer une sélection de fuseau horaire avec le champ de date pour garantir une représentation précise de la date-heure.

  • Accessibilité : Utilisez le DateTimeField en gardant à l'esprit l'accessibilité. Assurez-vous qu'il respecte les normes d'accessibilité, telles que la fourniture d'étiquettes appropriées et la compatibilité avec les technologies d'assistance.

  • Auto-remplir la date actuelle : Envisagez de fournir une option pour auto-remplir la date et l'heure actuelles en tant que valeur par défaut dans le champ de date-heure, si cela est approprié pour le cas d'utilisation de votre application.