Uso
Descripción general
El selector de fecha es un componente que se consta de dos elementos principales: un campo de selector de fecha y un calendario desplegable. El componente calendario representa visualmente una fecha y proporciona una experiencia de navegación coherente a través de las vistas de día, mes y año. Este calendario integrado permite a los usuarios buscar y seleccionar fechas dentro de una vista.
Cuándo se debe utilizar
- Para seleccionar una fecha cercana a la actual.
- Para seleccionar una fecha y guardarla en un campo de entrada.
- Para navegar a través de diferentes vistas de fechas, como días, meses y años.
- Para una representación visual de la fecha.
Cuándo no se debe utilizar
- Para seleccionar una fecha en el pasado o en el futuro lejanos. En este caso, utilice la entrada de fecha.
- Para seleccionar un intervalo de fechas. En este caso, utilice el intervalo de fechas.
- Para seleccionar solo el mes y el año, sin un día específico. En este caso, utilice el selector de mes.
- Para seleccionar solo el año, sin especificar el mes ni el día. En este caso, utilice el selector de año.
- Para seleccionar una hora específica. En este caso, utilice el selector de hora.
Consulte también
Anatomía
El componente selector de fecha consta de los siguientes elementos:
- Campo selector de fecha: Campo de entrada donde el usuario puede ingresar manualmente el día, el mes y el año.
- Ícono de calendario: Botón de ícono que activa el calendario desplegable cuando se hace clic en él.
- Botón mes anterior: Control de navegación para ver y seleccionar fechas del mes anterior.
- Botón mes: Control para seleccionar un mes diferente.
- Botón año: Control para seleccionar un año diferente.
- Botón mes siguiente: Control de navegación para ver y seleccionar fechas del mes siguiente.
- Fecha actual: La fecha actual, con una línea debajo para indicarla visualmente.
- Fecha seleccionada: Fecha específica elegida por el usuario y resaltada o destacada dentro de la interfaz del selector de fecha.
- Botón “Hoy”: Botón que rellena automáticamente el campo del selector de fecha con el día, el mes y el año actuales cuando se hace clic en él.
El formato de la fecha que se muestra en el selector de fecha depende de la configuración regional del usuario. Esto significa que el formato de fecha variará según la ubicación del usuario y la configuración de idioma.
Por ejemplo, en los Estados Unidos, el formato de la fecha suele ser MM/DD/YYYY, mientras que en muchos países europeos, el formato es DD/MM/YYYY.
El formato de fecha se muestra como un marcador de posición dentro del selector de fecha para ayudar al usuario a ingresar la fecha. Esto asegura que el formato permanezca visible durante todo el proceso de ingreso de información.
Un marcador de posición dentro del campo de entrada guía a los usuarios sobre el formato de fecha previsto a medida que escribe.
Contenido
Pautas generales de redacción
- En todos los aspectos del diseño de las interfaces de productos de Guidewire, utilice mayúsculas como se usan en las oraciones. No use mayúsculas en todas las palabras.
- Use verbos en tiempo presente y voz activa en la mayoría de las situaciones.
- Use contracciones comunes para darle al texto un tono más natural e informal (pauta correspondiente al inglés).
- Use un lenguaje sencillo. Evite la jerga innecesaria y el lenguaje complejo.
- Las palabras y las oraciones deben ser breves.
Inclusión de un rótulo
Rotule el selector de fecha con texto claro y descriptivo. Este rótulo debe comunicar su propósito y el tipo específico de fecha que se selecciona.
Coloque un rótulo permanente fuera del campo.
No utilice texto de marcador de posición como sustituto del rótulo.
Agregue texto de ayuda si fuera significativo
Use texto de ayuda para proporcionar contexto y comunicar qué fecha se debe seleccionar. Estos son algunos ejemplos de lo que podría incluir:
- Sugerencias que ayuden al usuario a elegir la fecha adecuada.
- Más contexto de por qué el usuario debe seleccionar una fecha específica.
Utilice el texto de ayuda solo para la información pertinente. Evite repetir los mismos detalles que aparecen en el rótulo. Escriba el texto de ayuda con mayúsculas como se usan en las oraciones, y use 1 o 2 oraciones cortas y completas que terminen con un punto.
Utilice texto de ayuda para mostrar el contexto.
No use texto de ayuda que simplemente repita la misma información que aparece en el rótulo.
Comportamientos
Estados
El componente selector de fecha se comporta como un campo de entrada, con los mismos estados interactivos.
Interacciones
Ratón
Los usuarios pueden ingresar el día, el mes y el año manualmente en el campo selector de fecha o hacer clic en el ícono de calendario para seleccionar el día, el mes y el año de un menú desplegable.
Teclado
El selector de fecha se expande y se contrae con Spacebar. Los usuarios pueden navegar por las opciones utilizando las teclas de flecha y seleccionar por medio de la tecla Spacebar o Enter .
Aparece un widget de calendario cuando el usuario se desplaza con el tabulador al campo de entrada selector de fecha. La fecha actual se resalta y los usuarios que solo usan teclado pueden ingresar la fecha manualmente aquí. Los usuarios también pueden colocar el foco del teclado en el widget presionando la tecla de flecha hacia abajo cuando está expandido. Navegue por el calendario con las teclas de flecha. Los botones “Anterior”, “Mes”, “Año” y “Siguiente” pueden recibir el foco con la tecla Tab cuando el widget está abierto.
Lector de pantalla
Se informa a los usuarios el valor de fecha completado automáticamente, cuando van al campo de entrada del selector de fecha con el tabulador, y que este valor está seleccionado actualmente. Se puede ingresar la fecha manualmente desde este campo de entrada. Si bien el foco permanece en la fecha completada automáticamente, también hay un widget de calendario disponible. Los usuarios también pueden mover el foco hacia el widget presionando la tecla de flecha hacia abajo. La navegación por la parte del calendario del widget se realiza con las teclas de flecha, y el valor actualmente en foco es narrado por los lectores de pantalla mediante un atributo WAI-ARIA aria-label. Los botones “Anterior”, “Mes”, “Año” y “Siguiente” pueden recibir el foco con la tecla Tab cuando el widget está abierto. El selector de fecha de React no habilita actualmente la navegación por teclado al enlace “Hoy”.
El componente selector de fecha permite a los usuarios mover el cursor de inserción (cursor de texto parpadeante) entre diferentes secciones de la fecha (MM/DD/AAAA). Sin embargo, los usuarios no pueden eliminar dígitos individuales dentro de una sección. Al eliminar cualquier dígito, se borra toda la sección (MM, DD o AAAA), lo que requiere que los usuarios la vuelvan a escribir. Este comportamiento es igual en todos los componentes de fecha, donde la máscara de entrada da formato a la entrada mientras el usuario escribe.
Accesibilidad
Este componente de Jutro ha sido validado para cumplir con las pautas de accesibilidad de WCAG 2.2 AA en su configuración base predeterminada. Esto incluye garantizar que se cumpla lo siguiente:
- La relación de contraste de los elementos textuales con respecto a su fondo es superior a 4,5:1.
- El contenido no textual que debe transmitir significado (como íconos e indicadores de foco) tiene una relación de contraste de al menos 3:1 con sus colores adyacentes.
- El elemento se puede operar con teclado, así como con mouse.
- Se puede acceder al contenido mediante lectores de pantalla, como JAWS y VoiceOver.
El cumplimiento de los criterios de accesibilidad depende, en última instancia, de cómo se implementa y personaliza este componente. Los cambios realizados por el autor del contenido pueden afectar la accesibilidad. Para obtener más información sobre nuestro modelo de responsabilidad compartida, revise nuestra declaración completa sobre accesibilidad de Jutro.
Cuando utilice este componente, asegúrese de que el rótulo comunique claramente la fecha que el usuario debe ingresar o seleccionar.
Código
<DatePicker
label="Choose Date"
onChange={(event, value) =>
console.log('The date chosen is', value.day, value.month, value.year)
}
/>
Instrucción de importación
import { DatePicker } from '@jutro/components';
Contrato de componentes
Asegúrese de comprender la superficie de la API de componentes del sistema de diseño, así como sus implicaciones, ventajas y desventajas. Obtenga más información en nuestra introducción a la API de componentes.
Propiedades
labelobligatorio
DescripciónLabel associated with the input field, also passed as a default value to 'aria-label'.
className
DescripciónCSS class name for this component.
disabled
DescripciónIf set to true, the component is rendered in disabled state.
Tipo'vshort' | 'short' | 'long' | 'abbreviated' | 'full'
Valor predeterminado'short'
displayOnly
DescripciónIf 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.
hideLabel
DescripciónIf set to true, the label is not visible.
DescripciónHides the Today button in the calendar.
initialValue
Tipo{ day: number, month: number, year: number }
DescripciónInitial value of the input. Value must be in object format with day, month, and year property where month is indexed from 1. If the value prop is specified along with this prop, this prop's value is discarded.
labelPosition
maxDate
Tipo{ day: number, month: number, year: number }
DescripciónMaximum allowed day value.
minDate
Tipo{ day: number, month: number, year: number }
DescripciónMinimum allowed day value.
onBlur
Tipofunction (FocusEvent<HTMLInputElement>)
DescripciónA callback called after the component is focused.
onChange
Tipofunction (React.ChangeEvent<HTMLInputElement>, { day: number, month: number, year: number })
DescripciónCallback invoked when component value is changed.
onFocus
Tipofunction (FocusEvent<HTMLInputElement>)
DescripciónA callback called after the component is focused.
placeholder
DescripciónPlaceholder to display on an empty component.
readOnly
DescripciónIf set to true, component is rendered in a read-only state. For values in plain text, consider using displayOnly.
required
DescripciónIf set to true, the component is rendered as required and the label includes an asterisk.
secondaryLabel
DescripciónSecondary label text to display.
stateMessages
DescripciónAn object with a list of error messages for the current state.
Tipo{ text: intlMessageShape, trigger: string } | intlMessageShapetext
DescripciónText to show tooltip content.
trigger
DescripciónThe trigger to show the tooltip.
DescripciónText to be displayed in the tooltip or tooltip object that includes: text - to show tooltip content, trigger - to set tooltip trigger.
value
Tipo{ day: number, month: number, year: number }
DescripciónValue of the input. Takes precedence over initialValue. The value must be in object format with day, month, and year property where month is indexed from 1. If this prop is passed, the component works in a controlled mode and its value will change only if this prop changes.
Ganchos
No hay ganchos para Selector de fechas.
Claves de traducción
El componente selector de fechas define las siguientes claves de traducción:
| Clave | Se usa para |
|---|
| jutro-components.fields.DatePicker.chooseDate | El texto de rótulo para el campo de entrada. |
| jutro-components.fields.DatePicker.placeholderDay | La parte del día del marcador de posición. Deben ser dos caracteres repetidos. |
| jutro-components.fields.DatePicker.placeholderMonth | La parte del mes del marcador de posición. Deben ser dos caracteres repetidos. |
| jutro-components.fields.DatePicker.placeholderYear | La parte del año del marcador de posición. Deben ser cuatro caracteres repetidos. |
selector de fechas también hereda las siguientes traducciones:
| Clave | Se usa para |
|---|
| jutro-components.DateCalendar.previousMonth | El texto del rótulo para el botón Mes anterior. |
| jutro-components.DateCalendar.nextMonth | El texto del rótulo para el botón del mes siguiente. |
| jutro-components.DateCalendar.currentDay | El texto del rótulo para el botón Ir a la fecha actual. |
| jutro-components.DateCalendar.currentDayAriaLabel | El texto del rótulo para el botón para seleccionar la fecha actual como valor. |
| jutro-components.MonthSkeleton.previousYear | El texto del rótulo para el botón del año anterior. |
| jutro-components.MonthSkeleton.nextYear | El texto del rótulo para ir al botón del año siguiente. |
| jutro-components.MonthSkeleton.currentMonth | El texto del rótulo para ir al botón del mes actual. |
| jutro-components.MonthSkeleton.currentMonthAriaLabel | El texto del rótulo para el botón para seleccionar el mes actual como valor. |
| jutro-components.YearCalendar.previousYears | El texto del rótulo para el botón de intervalo del año anterior. |
| jutro-components.YearCalendar.currentYear | El texto del rótulo para el botón Ir al año actual. |
| jutro-components.YearCalendar.currentYearAriaLabel | El texto del rótulo para el botón para seleccionar el año actual como valor. |
El formato de la fecha se determina de acuerdo con la configuración regional seleccionada. Por ejemplo, si la configuración regional es en-US, la fecha 20 de enero de 2024 tiene el formato “01/20/2024”. Si la configuración regional es en-GB, tendrá el formato “20/01/2024”.
Escotillas de escape
Para obtener más información, consulte nuestra documentación sobre escotillas de escape.
Ejemplos
Consulte la sección Uso para obtener detalles sobre cómo diseñar un selector de fechas correctamente y las diferentes opciones de configuración que ofrecemos.
Ejemplo de selector de fecha básico
Puede agregar una entrada que permita a un usuario ingresar una fecha, ya sea manualmente o a través de un modal de calendario.
<DatePicker
label="Choose date"
onChange={(event, value) =>
console.log('The date chosen is', value.day, value.month, value.year)
}
/>
Ejemplo mín./máx.
Es posible limitar el intervalo de fechas que un usuario puede seleccionar.
Note: Esto no incluye la validación, solo limita las opciones en un menú desplegable. El usuario puede ingresar manualmente cualquier fecha.
<DatePicker
label="Choose date"
minDate={{ day: 1, month: 1, year: 2022 }}
maxDate={{ day: 31, month: 12, year: 2023 }}
/>
Ejemplo de validación
Puede utilizar la propiedad onChange para llamar a una función que actualiza stateMessages para mostrar errores al usuario.
En el siguiente ejemplo, se muestran errores para fechas no válidas o fechas que no están en 2022.
function DatePickerMinMaxValidation() {
const [validationMessages, setValidationMessages] = useState({});
const minDate = { day: 1, month: 1, year: 2022 };
const maxDate = { day: 31, month: 12, year: 2022 };
function JutroDateToString(date) {
return `${date.year}-${String(date.month).padStart(2, '0')}-${String(
date.day
).padStart(2, '0')}`;
}
const parseErrorCode = (errorObject: { errorCode?: string }) => {
if (!errorObject) {
return;
}
const { errorCode } = errorObject;
if (errorCode === 'INVALID_DATE') {
return { error: ['Please enter a valid date.'] };
}
if (errorCode === 'MIN_EXCEEDED') {
return {
error: [`Please enter a date after ${JutroDateToString(minDate)}.`],
};
}
if (errorCode === 'MAX_EXCEEDED') {
return {
error: [`Please enter a date before ${JutroDateToString(maxDate)}.`],
};
}
};
const onChange = useCallback((e, newValue, errorObject) => {
setValidationMessages({});
const errorDetected = parseErrorCode(errorObject);
if (errorDetected) {
setValidationMessages(errorDetected);
}
}, []);
return (
<DatePicker
label="Choose date"
onChange={onChange}
minDate={minDate}
maxDate={maxDate}
stateMessages={validationMessages}
/>
);
}
Registro de cambios
10.13.0
Se agregó una ruta de importación desde @jutro/components para el componente DatePicker.
La ruta de importación anterior desde @jutro/components/new se eliminará en una futura versión principal.
Recomendamos a los usuarios ejecutar el siguiente comando para aplicar un codemod, a fin de actualizar las rutas de importación en su código.
jutro codemod:apply --name=MigrateDatePickerImportFromNew
Para obtener más información sobre los codemods de Jutro, consulte la documentación sobre codemods.
10.9.0
Tipo de propiedad icon extendida
El tipo de propiedad icon del componente obsoleto DateField se ha extendido a string | React.ComponentType.
Valor predeterminado de icon modificado
El valor predeterminado de la propiedad icon del componente obsoleto DateField cambió de 'gw-check' a CheckIcon.
10.5.0
Se introdujo un nuevo componente @jutro/components/new/DatePicker que sustituye a DateField.
DateField todavía se puede importar desde @jutro/components/DateField, pero al hacerlo recibirá una advertencia de que está obsoleto.
