Sélecteur d'année

Sélecteur d'année dans Storybook

Utilisation

Présentation

Le sélecteur d'année est un élément de contrôle dans lequel l'utilisateur sélectionne une année spécifique dans un calendrier ou la saisit manuellement. Ce composant est couramment utilisé dans les applications d'assurance où les utilisateurs doivent indiquer une année, par exemple l'année où ils ont subi une perte couverte par leur assurance Multirisque Habitation.

Quand l'utiliser

Lorsque l'utilisateur doit sélectionner une année.

Quand ne pas l'utiliser

• Lorsque l'utilisateur doit saisir une année passée ou future lointaine. Dans ce cas, utilisez la saisie de date.
• Lorsque l'utilisateur doit sélectionner le mois, le jour et l'année. Dans ce cas, utilisez le sélecteur de date.
• Lorsque l'utilisateur doit sélectionner à la fois un mois et une année. Dans ce cas, utilisez le sélecteur de mois.

Voir également

• Champ de date simple
• Sélecteur de date
• Plage de dates
• Sélecteur d'heure
• Sélecteur de mois
• Valeur de date et d'heure

Formatage

Structure

Le composant Sélecteur d'année est constitué des éléments suivants :

1. Champ du sélecteur de date : champ de saisie dans lequel l'utilisateur peut saisir manuellement l'année.
2. Icône Calendrier : bouton avec icône qui déclenche le calendrier déroulant lorsque l'utilisateur clique dessus.
3. Bouton Année précédente : commande de navigation permettant d'afficher et de sélectionner une année antérieure dans la plage du sélecteur.
4. Bouton Année suivante : commande de navigation permettant d'afficher et de sélectionner une année ultérieure dans la plage du sélecteur.
5. Année sélectionnée : année spécifique choisie par l'utilisateur et mise en surbrillance ou mise en évidence dans l'interface du sélecteur d'année.
6. Bouton « Année en cours » : bouton qui renseigne automatiquement le champ du sélecteur d'année avec l'année en cours lorsque l'utilisateur clique dessus.

Format de date

Un espace réservé YYYY dans le champ de saisie guide les utilisateurs sur le format annuel attendu au fur et à mesure de leur saisie.

Contenu

Directives générales relatives à la rédaction

• Mettez une majuscule en début de phrase pour tous les aspects relatifs à la conception des interfaces de produit Guidewire. Ne mettez pas la 1re lettre du 1er mot du titre en majuscule.
• Utilisez des verbes au présent et la forme active dans la plupart des cas.
• Utilisez des contractions courantes pour donner à votre texte un ton plus naturel et informel.
• Utilisez un langage simple. Évitez tout jargon inutile et les formulations complexes.
• Utilisez des termes et des phrases concis.

Inclure une étiquette

Renseignez un texte clair et descriptif pour l'étiquette du sélecteur d'année. Cette étiquette doit indiquer sa fonction et le type spécifique d'année sélectionné.

Placez une étiquette permanente en dehors du champ.

N'utilisez pas de texte de l'espace réservé pour remplacer une étiquette.

Ajoutez un texte d'aide si cela est utile

Utilisez le texte d'aide pour fournir du contexte et indiquer l'année à sélectionner. Voici quelques exemples de ce que vous pouvez inclure :

• Des conseils qui aident l'utilisateur à choisir l'année appropriée
• Plus de contexte pour expliquer pourquoi l'utilisateur doit sélectionner une année spécifique

N'utilisez le texte d'aide que pour les informations pertinentes. Évitez de reformuler les détails qui apparaissent dans l'étiquette. Rédigez le texte d'aide en 1 ou 2 phrases courtes et complètes se terminant par un point. Mettez une majuscule en début de phrase.

N'utilisez pas de texte d'aide pour indiquer le contexte.

N'utilisez pas le texte d'aide pour simplement reformuler les mêmes informations que celles qui apparaissent dans l'étiquette.

Comportements

États

Le composant Sélecteur d'année se comporte comme un champ de saisie, avec les mêmes états interactifs.

Interactions

Souris

Les utilisateurs peuvent saisir l'année manuellement dans le champ du sélecteur d'année ou cliquer sur l'icône du calendrier pour sélectionner l'année dans une liste déroulante.

Clavier

Le sélecteur de date est développé et réduit avec Spacebar. Les utilisateurs naviguent parmi les options à l'aide des touches fléchées et les sélectionne à l'aide de la touche Spacebar ou Enter.

Un widget de calendrier apparaît lorsque l'utilisateur sélectionne le champ de saisie de sélecteur d'année. La date du jour est mise en surbrillance et les utilisateurs qui ne se servent que du clavier peuvent entrer la date manuellement ici. Les utilisateurs peuvent également placer le focus clavier sur le widget en appuyant sur la touche fléchée vers le bas lorsqu'il est développé. Parcourez le calendrier avec les touches fléchées. Il est possible de mettre les boutons « Précédent », « Mois », « Année » et « Suivant » en évidence via la touche Tab lorsque le widget est ouvert.

Lecteur d'écran

Les utilisateurs sont informés de la valeur de date préremplie lorsqu'ils accèdent au champ de saisie du sélecteur de date et du fait que cette valeur est actuellement sélectionnée. La date peut être saisie manuellement à partir de ce champ de saisie. Bien que le focus reste placé sur la date préremplie, un widget de calendrier est également disponible. Les utilisateurs peuvent également déplacer le focus sur le widget en appuyant sur la touche fléchée vers le bas. La navigation dans la partie calendrier du widget s'effectue à l'aide des touches fléchées, et la valeur actuellement sélectionnée est lue par les lecteurs d'écran via un attribut WAI-ARIA aria-label. Il est possible de mettre les boutons « Précédent », « Mois », « Année » et « Suivant » en évidence via la touche Tab lorsque le widget est ouvert. Le sélecteur de date React n'active actuellement pas la navigation au clavier vers le lien « Aujourd'hui ».

Gestion des entrées

Le composant Sélecteur d’année ne permet pas aux utilisateurs de contrôler le caret (le curseur de texte clignotant) d’une manière qui permette la suppression partielle de la valeur. Les utilisateurs peuvent cliquer dans le champ pour déplacer le caret, mais la suppression d’un chiffre efface la valeur entière, ce qui oblige les utilisateurs à retaper l’année depuis le début. Ce comportement est constant dans tous les composants de date, où le masque de saisie formate la saisie au fur et à mesure de la saisie de l’utilisateur.

Accessibilité

Ce composant a été validé pour répondre aux directives d’accessibilité WCAG 2.2 AA dans sa configuration de base par défaut. Il s’agit notamment de s’assurer que :

• Le rapport de contraste des éléments textuels par rapport à leur arrière-plan est supérieur à 4.5:1.
• Le contenu non textuel qui doit transmettre le sens (comme les icônes et les indicateurs de focus) a un rapport de contraste d’au moins 3:1 avec ses couleurs adjacentes.
• Cet élément peut être utilisé à l’aide d’un clavier et d’une souris.
• Le contenu est accessible à l’aide de lecteurs d’écran, tels que JAWS et VoiceOver.

La conformité de l’accessibilité dépend en définitive de la façon dont ce composant est implémenté et personnalisé. Les modifications apportées par l’auteur du contenu peuvent affecter l’accessibilité. Pour en savoir plus sur notre modèle de responsabilité partagée, consultez notre Déclaration d’accessibilité Jutro complète.

Lorsque vous utilisez ce composant, assurez-vous que l'étiquette indique clairement l'année que l'utilisateur doit saisir ou sélectionner.

Code

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

Instruction d'importation

import { YearPicker } from '@jutro/components';

Cahier des charges du composant

Assurez-vous de comprendre la surface de l'API des composants du système de conception, ainsi que les implications et les compromis. Pour en savoir plus, reportez-vous à notre introduction à l'API des composants.

Propriétés

labelobligatoire

Type

IntlMessageShape

Description

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

className

Type

string

Description

CSS class name for this component.

disabled

Type

boolean

Description

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

displayOnly

Type

boolean

Description

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

Type

boolean

Description

Hides the current year button in the calendar.

hideLabel

Type

boolean

Description

If set to true, the label is not visible.

id

Type

string

Description

Unique identifier for the component.

initialValue

Type

{ year: number }

Description

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

Type

'top|'left'

Description

Allows to select label position.

maxYear

Type

{ year: number }

Description

Maximum allowed year value.

minYear

Type

{ year: number }

Description

Minimum allowed year value.

onBlur

Type

function (FocusEvent<HTMLInputElement>)

Description

A callback called after the component is focused.

onChange

Type

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

Description

Callback invoked when component value is changed.

onFocus

Type

function (FocusEvent<HTMLInputElement>)

Description

A callback called after the component is focused.

placeholder

Type

string

Description

Placeholder to display on an empty component.

readOnly

Type

boolean

Description

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

required

Type

boolean

Description

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

secondaryLabel

Type

string

Description

Secondary label text to display.

stateMessages

Type

{ error: string[] }

Description

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

tooltip

Type

{ text: intlMessageShape, trigger: string } | intlMessageShape

text

Type

IntlMessageShape

Description

Text to show tooltip content.

trigger

Type

string

Description

The trigger to show the tooltip.

Description

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

value

Type

{ year: number }

Description

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.

Crochets

Aucun crochet n'est disponible pour YearPicker.

Clés de traduction

Le composant YearPicker définit une clé de traduction :

Clé	Utilisée pour
jutro-components.fields.YearPicker.chooseYear	Texte de l'étiquette du champ de saisie.

Le composant YearPicker hérite en outre des traductions suivantes :

Clé	Utilisée pour
jutro-components.YearCalendar.previousYears	Texte de l'étiquette du bouton de plage de l'année précédente.
jutro-components.YearCalendar.currentYear	Texte de l'étiquette du bouton Accéder à l'année en cours.
jutro-components.YearCalendar.currentYearAriaLabel	Texte de l'étiquette du bouton permettant de sélectionner l'année en cours comme valeur.
jutro-components.fields.DatePicker.placeholderYear	Partie année de l'espace réservé. Doit comporter quatre caractères répétés.

Format et localisation des dates

La date est formatée en fonction des paramètres régionaux sélectionnés. Par exemple, si le paramètre régional est en-US, la date du 20 janvier 2024 prend le format « 01/20/2024 ». Si le paramètre régional est en-GB, le format est « 20/01/2024 ».

Portes de sortie

Pour en savoir plus, reportez-vous à notre documentation sur les portes de sortie.

Exemples

Consultez la section Utilisation pour découvrir comment concevoir correctement un sélecteur d'année et connaître les différentes options de configuration que nous proposons.

Exemple de sélecteur d’année de base

Vous pouvez autoriser un utilisateur à sélectionner une année à l'aide des données saisies.

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

Exemple d'erreur

La propriété stateMessages peut être utilisée pour afficher une erreur.

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

Exemple Min/Max

Vous pouvez utiliser les propriétés minYear et maxYear pour limiter les années qu'un utilisateur peut sélectionner.

Note: Cela n'inclut pas la validation, cela limite uniquement les options dans une liste déroulante. Un utilisateur peut saisir manuellement n'importe quelle année.

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

Exemple contrôlé

Vous pouvez contrôler le sélecteur d'année en transmettant la propriété value. Ceci est utile si vous souhaitez utiliser le sélecteur d'année comme composant contrôlé.

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>

Journal des modifications

10.13.0

Un chemin d’importation à partir de @jutro/components a été ajouté pour le composant YearPicker.

L’ancien chemin d’importation à partir de @jutro/components/new sera supprimé dans une prochaine version majeure.

Il est conseillé aux utilisateurs d’exécuter la commande suivante pour appliquer un codemod afin de mettre à jour les chemins d’importation dans votre code.

jutro codemod:apply --name=MigrateYearPickerImportFromNew

Pour en savoir plus sur les codemods Jutro, reportez-vous à la documentation sur les codemods.

10.5.0

Le nouveau composant @jutro/components/new/YearPicker a été introduit et remplace YearField.

YearField peut toujours être importé depuis @jutro/components/YearField, mais vous recevrez un avertissement indiquant qu'il est obsolète.