Selector de año

Selector de año en Storybook

Uso

Descripción general

El selector de año es un elemento de control en el que el usuario selecciona un año específico de un calendario o lo ingresa manualmente. Este componente se usa con frecuencia en aplicaciones de seguros en las que los usuarios necesitan especificar un año, como el año en que sufrieron una pérdida cubierta por su seguro de vivienda.

Cuándo se debe utilizar

Cuando el usuario debe seleccionar un año.

Cuándo no se debe utilizar

• Cuando el usuario debe ingresar un año de un pasado o futuro lejanos. En este caso, utilice la entrada de fecha.
• Cuando el usuario debe seleccionar el mes, el día y el año. En este caso, utilice el selector de fecha.
• Cuando el usuario debe seleccionar un mes y un año. En este caso, utilice el selector de mes.

Consulte también

• Campo de fecha simple
• Selector de fechas
• Intervalo de fechas
• Selector de hora
• Selector de mes
• Valor de fecha y hora

Formato

Anatomía

El componente selector de año consta de los siguientes elementos:

1. Campo selector de fecha: Campo de entrada donde el usuario puede ingresar manualmente el año.
2. Ícono de calendario: Botón de ícono que activa el calendario desplegable cuando se hace clic en él.
3. Botón años anteriores: Control de navegación para ver y seleccionar de entre un conjunto anterior de años dentro del intervalo del selector.
4. Botón años siguientes: Control de navegación para ver y seleccionar de entre un conjunto posterior de años dentro del intervalo del selector.
5. Año seleccionado: Año específico elegido por el usuario y resaltado o destacado dentro de la interfaz del selector de año.
6. Botón “Año actual”: Botón que completa automáticamente el campo selector de año con el año actual cuando se hace clic en él.

Formato de fecha

Un marcador de posición YYYY dentro del campo de entrada guía a los usuarios en cuanto al formato de año previsto a medida que escriben.

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 año con texto claro y descriptivo. Este rótulo debe comunicar su propósito y el tipo específico de año 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é año se debe seleccionar. Estos son algunos ejemplos de lo que podría incluir:

• Sugerencias que ayuden al usuario a elegir el año adecuado.
• Más contexto de por qué el usuario debe seleccionar un año específico.

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 año se comporta como un campo de entrada, con los mismos estados interactivos.

Interacciones

Ratón

Los usuarios pueden ingresar el año manualmente en el campo selector de año o hacer clic en el ícono de calendario para seleccionar el año en 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 año. 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”.

Manejo de entradas

El componente selector de año no permite a los usuarios controlar el cursor de inserción (cursor de texto parpadeante) de manera que permita la eliminación parcial del valor. Los usuarios pueden hacer clic dentro del campo para mover el cursor de inserción, pero, al eliminar cualquier dígito, se borra todo el valor, lo que requiere que los usuarios tengan que volver a escribir el año desde el principio. 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 el año que el usuario debe ingresar o seleccionar.

Código

<YearPicker
  label={{
    id: 'year-picker',
    defaultMessage: 'Enter year',
  }}
  onChange={(event, value) => console.log('The year chosen is', value.year)}
/>

Instrucción de importación

import { YearPicker } 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

Tipo

IntlMessageShape

Descripción

Label associated with the input field, also passed as a default value to 'aria-label'.

className

Tipo

string

Descripción

CSS class name for this component.

disabled

Tipo

boolean

Descripción

If set to true, the component is rendered in disabled state.

displayOnly

Tipo

boolean

Descripción

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

hideCurrentYearButton

Tipo

boolean

Descripción

Hides the current year button in the calendar.

hideLabel

Tipo

boolean

Descripción

If set to true, the label is not visible.

id

Tipo

string

Descripción

Unique identifier for the component.

initialValue

Tipo

{ year: number }

Descripción

Initial value of the input. The value must be in an object format with a year property. If a value prop is specified along with this prop, this prop's value is discarded.

labelPosition

Tipo

'top|'left'

Descripción

Allows to select label position.

maxYear

Tipo

{ year: number }

Descripción

Maximum allowed year value.

minYear

Tipo

{ year: number }

Descripción

Minimum allowed year value.

onBlur

Tipo

function (FocusEvent<HTMLInputElement>)

Descripción

A callback called after the component is focused.

onChange

Tipo

function (React.ChangeEvent<HTMLInputElement>, { year: number })

Descripción

Callback invoked when component value is changed.

onFocus

Tipo

function (FocusEvent<HTMLInputElement>)

Descripción

A callback called after the component is focused.

placeholder

Tipo

string

Descripción

Placeholder to display on an empty component.

readOnly

Tipo

boolean

Descripción

If set to true, component is rendered in a read-only state. For values in plain text, consider using displayOnly.

required

Tipo

boolean

Descripción

If set to true, the component is rendered as required and the label will display an asterisk.

secondaryLabel

Tipo

string

Descripción

Secondary label text to display.

stateMessages

Tipo

{ error: string[] }

Descripción

An object with a list of error messages for the current state.

tooltip

Tipo

{ text: intlMessageShape, trigger: string } | intlMessageShape

text

Tipo

IntlMessageShape

Descripción

Text to show tooltip content.

trigger

Tipo

string

Descripción

The trigger to show the tooltip.

Descripción

Text to be displayed in the tooltip or tooltip object that includes: text - to show tooltip content, trigger - to set tooltip trigger.

value

Tipo

{ year: number }

Descripción

Value of the input. Takes precedence over initialValue. The value must be in object format with a year property. 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 año.

Claves de traducción

El componente YearPicker define una clave de traducción:

Clave	Se usa para
jutro-components.fields.YearPicker.chooseYear	El texto de rótulo para el campo de entrada.

El componente YearPicker también hereda las siguientes traducciones:

Clave	Se usa para
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.
jutro-components.fields.DatePicker.placeholderYear	La parte del año del marcador de posición. Deben ser cuatro caracteres repetidos.

Formato y localización de fechas

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 año correctamente y las diferentes opciones de configuración que ofrecemos.

Ejemplo de selector de año básico

Puede permitir que el usuario seleccione un año utilizando la información proporcionada.

<YearPicker
  label={{
    id: 'year-picker',
    defaultMessage: 'Enter year',
  }}
  onChange={(event, value) => console.log('The year chosen is', value.year)}
/>

Ejemplo de error

La propiedad stateMessages se puede utilizar para mostrar un error.

<YearPicker
  label={{
    id: 'year-picker',
    defaultMessage: 'Enter year',
  }}
  stateMessages={{ error: ['This is an error message'] }}
/>

Ejemplo mín./máx.

Puede utilizar las propiedades minYear y maxYear para limitar los años 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 año.

<YearPicker
  label={{
    id: 'year-picker',
    defaultMessage: 'Enter year',
  }}
  minYear={{ year: 2020 }}
  maxYear={{ year: 2030 }}
/>

Ejemplo controlado

Puede controlar el selector de año pasando la propiedad value. Esto es útil si desea utilizar el selector de año como componente controlado.

const [picked, setYear] = React.useState({ year: undefined });

    function handleYearChange(event, value) {
        setYear(value);
    }

<YearPicker
    label={{
    id: 'year-picker-label',
    defaultMessage: 'Select year',
    }}
    onChange={handleYearChange}
    value={picked}
/>
<div>
    {picked && picked.year ? (
        <>The selected year is {picked.year}.</>
    ) : (
        <>Waiting for the user to specify year.</>
    )}
</div>

Registro de cambios

10.13.0

Se agregó una ruta de importación desde @jutro/components para el componente YearPicker.

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=MigrateYearPickerImportFromNew

Para obtener más información sobre los codemods de Jutro, consulte la documentación sobre codemods.

10.5.0

Se introdujo un nuevo componente @jutro/components/new/YearPicker que sustituye a YearField.

YearField todavía se puede importar desde @jutro/components/YearField, pero al hacerlo recibirá una advertencia de que está obsoleto.