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, abarcando 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 Field compartida, 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 utilizado 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 de manera eficiente, reservar citas y gestionar sus calendarios al darles un único 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 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 la hora de cuándo ocurren eventos o cuándo un usuario envía datos.

  2. Gestión de tareas y plazos: Los DateTimeFields son valiosos en aplicaciones que implican 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 utilizando un objeto LocalDateTime del paquete java.time. Esto proporciona un control preciso sobre los componentes de fecha y hora de la entrada.

Mientras que el valor del lado del cliente se renderiza en función de 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 el valor programáticamente, 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 cruda, 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 usar 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ática:

  • fromDateTime(String dateTimeAsString): Convierte una cadena de fecha y hora en formato yyyy-MM-ddTHH:mm:ss a un objeto LocalDateTime que luego puede ser utilizado con esta clase, o en otros lugares.

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

  • isValidDateTime(String dateTimeAsString): Comprueba si la cadena dada es una fecha y hora válida en 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 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 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 usar 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 a través de diferentes zonas horarias, considera incorporar la selección de zona horaria junto al campo de fecha para asegurar una representación precisa de la fecha y la hora.

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

  • 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.