Saltar al contenido principal

DateTimeField

Abrir en ChatGPT
Sombra dwc-field 23.02
Java API

El componente DateTimeField permite a los usuarios ingresar tanto una fecha como una hora en un solo campo, cubriendo año, mes, día, horas y minutos. Valida la entrada para asegurar precisión y puede presentar un selector de fecha y hora para facilitar la selección.

Usando DateTimeField​

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.

DateTimeField extiende la clase compartida Field, que proporciona características comunes a todos los componentes de campo. El siguiente ejemplo crea un DateTimeField etiquetado para seleccionar una fecha y hora de salida.

Mostrar Código

Usos​

El DateTimeField es mejor utilizarlo en escenarios donde capturar o mostrar tanto la fecha como la hora es esencial para tu aplicación. Aquí hay algunos ejemplos de cuándo usar el DateTimeField:

  1. Programación de eventos y calendarios: Permite a los usuarios programar eventos, reservar citas y gestionar sus calendarios de manera eficiente al ofrecerles un solo componente que les permite elegir la fecha y la hora.
  1. Check-in y check-out: Facilita la selección de horarios de check-in y check-out por parte del usuario cuando el periodo puede abarcar varios días.

  1. Registro de datos y marcas de tiempo: Utiliza DateTimeFields para aplicaciones que implican registrar la fecha y hora de cuando ocurren eventos o cuando un usuario envía datos.

  2. Gestión de tareas y plazos: DateTimeFields son valiosos en aplicaciones que involucran gestión de tareas o establecimiento de plazos donde tanto la fecha como la hora son relevantes para una programación precisa.

Valor del campo (LocalDateTime)​

Internamente, el componente DateTimeField representa su valor usando un objeto LocalDateTime del paquete java.time. Esto proporciona un control preciso sobre ambos componentes, la fecha y la hora de la entrada.

Mientras que el valor del lado del cliente se representa según la configuración regional del navegador del usuario (por ejemplo, formatos de fecha y hora que coinciden con las convenciones locales), el valor analizado sigue una estructura estricta y predecible: yyyy-MM-ddTHH:mm:ss.

Obtener y establecer el valor​

Para recuperar el valor actual, utiliza el método getValue():

LocalDateTime value = dateTimeField.getValue();

Para establecer programáticamente el valor, utiliza el método setValue():

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

Usando setText()​

Si prefieres establecer el valor a través de una cadena sin procesar, debe seguir el formato exacto de yyyy-MM-ddTHH:mm:ss.

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

dateTimeField.setText("24-04-27T14:30:00"); // inválido
advertencia

Al utilizar el método setText(), se lanzará una IllegalArgumentException si el componente no puede analizar la entrada en el formato yyyy-MM-ddTHH:mm:ss.

Utilidades estáticas​

La clase DateTimeField también proporciona los siguientes métodos de utilidad estáticos:

  • fromDateTime(String dateTimeAsString): Convierte una cadena de fecha y hora en formato yyyy-MM-ddTHH:mm:ss a un objeto LocalDateTime que luego se puede utilizar con esta clase o en otro lugar.

  • toDateTime(LocalDateTime dateTime): Convierte un objeto LocalDateTime a una cadena de fecha y hora en formato yyyy-MM-ddTHH:mm:ss.

  • isValidDateTime(String dateTimeAsString): Verifica si la cadena dada es una fecha y hora válida en el formato yyyy-MM-ddTHH:mm:ss. Esto devolverá un valor booleano verdadero si es así, falso de lo contrario.

Valor mínimo y máximo​

El valor mínimo​

Si el valor ingresado en el componente es anterior a la marca de tiempo mínima especificada, el componente fallará en la validación de restricciones. Cuando se establecen tanto los valores mínimo como máximo, el valor mínimo debe ser una marca de tiempo que sea igual o anterior al valor máximo.

// Establecer la marca de tiempo mínima permitida: 1 de enero de 2023 a las 08:00
dateTimeField.setMin(LocalDateTime.of(2023, 1, 1, 8, 0));

El valor máximo​

Si el valor ingresado en el componente es posterior a la marca de tiempo máxima especificada, el componente fallará en la validación de restricciones. Cuando se establecen tanto los valores mínimo como máximo, el valor máximo debe ser una marca de tiempo que sea igual o posterior al valor mínimo.

// Establecer la marca de tiempo máxima permitida: 31 de diciembre de 2023 a las 18:00
dateTimeField.setMax(LocalDateTime.of(2023, 12, 31, 18, 0));

Mejores prácticas​

Para asegurar una experiencia óptima del usuario al utilizar el componente DateTimeField, considera las siguientes mejores prácticas:

  • Visualización de fecha localizada: Localizar el formato de fecha e incorporar preferencias regionales asegura que las fechas se presenten en un formato familiar para el usuario.

  • Incluir zonas horarias: Si tu aplicación maneja información sensible al tiempo en diferentes zonas horarias, considera incorporar la selección de la zona horaria junto al campo de fecha para asegurar una representación precisa de la fecha y hora.

  • Accesibilidad: Utiliza el DateTimeField con la accesibilidad en mente. Asegúrate de que cumpla con los estándares de accesibilidad, como proporcionar etiquetas adecuadas y ser compatible con tecnologías de asistencia.

  • Autocompletar la fecha actual: Considera proporcionar una opción para autocompletar la fecha y hora actuales como valor predeterminado en el campo de fecha y hora, si es apropiado para el caso de uso de tu aplicación.