Lien asynchrone

Lien asynchrone dans Storybook

Utilisation

Présentation

Le composant AsyncLink permet d'accéder à une nouvelle page ou à un nouveau chemin, mais uniquement après avoir préalablement effectué certaines tâches ou vérifications. Vous pouvez l'utiliser pour contrôler quand et si l'utilisateur est redirigé en fonction de conditions ou d'opérations spécifiques.

Quand l'utiliser

Utilisez le composant AsyncLink pour :

• Vérifier les actions des utilisateurs, par exemple s'assurer qu'un formulaire a bien été soumis avant de passer à une nouvelle page.
• Charger des données, pour s'assurer que les données importantes pour la page suivante sont chargées avant la navigation.
• Effectuer des tâches telles que l'enregistrement des actions de l'utilisateur, le suivi du comportement de l'utilisateur, la demande de confirmation de l'utilisateur ou l'enregistrement de l'état actuel avant la redirection.

Quand ne pas l'utiliser

N'utilisez pas le composant AsyncLink pour :

• Navigation immédiate. Si une navigation immédiate est nécessaire sans conditions préalables ni vérifications, évitez d'utiliser le lien asynchrone. Utilisez plutôt le composant Lien.
• Navigation simple. Si la navigation n'implique aucune tâche asynchrone, telle que le chargement de données ou les actions utilisateur, l'utilisation d'un lien asynchrone peut introduire une complexité inutile. Utilisez plutôt le composant Lien.

Formatage

Structure

Le composant AsyncLink se compose des éléments suivants :

1. Libellé : texte descriptif qui fournit le contexte et explique où mène le lien.

Contenu

Le composant AsyncLink suit les instructions relatives au contenu du composant Lien.

Comportements

AsyncLink affiche un indicateur de chargement lors de la récupération du contenu. Il se compose de 3 points pulsés. L'indicateur de chargement permet de s'assurer que les utilisateurs sont informés de l'activité en cours.

AsyncLink gère les erreurs en présentant un message d'erreur ou une interface utilisateur de secours si nécessaire. Une fois l'opération terminée, il se met à jour pour afficher le contenu extrait.

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.

Suivez les conseils ci-dessous lors de l'utilisation de ce composant dans vos applications :

• Veillez à ce que tous les changements de couleur respectent le seuil requis de 4.5:1.
• Assurez-vous que les lecteurs d'écran transmettent l'état de chargement et les messages d'erreur éventuels.
• Évitez d'utiliser des mots et des phrases comme « Cliquez ici » ou « ici » en tant que texte de lien. Créez plutôt un texte de lien significatif qui fait sens en soi.

Code

Instruction d'importation

import { AsyncLink } from '@jutro/router/';

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

onTriggerobligatoire

Type

function

Description

Calls the method used to trigger the promise.

children

Type

React.ReactNode | intlMessageShape

Description

The children elements to render inside the Link.

disabled

Type

string

Description

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

failTo

Type

string

Description

The destination path when the promise is rejected.

failToMessage

Type

string

Description

The message shown when the promise is rejected. It is only shown if failTo is not provided.

message

Type

string

Description

The message shown when executing the trigger/promise.

to

Type

IntlMessageShape | { pathname?: IntlMessageShape; hash?: IntlMessageShape }

hash

Type

IntlMessageShape

Description

Hash to put in the URL.

pathname

Type

IntlMessageShape

Description

Link path.

Description

The destination path when the link is clicked. Use this for paths internal to the application.

toMessage

Type

string

Description

The message shown when the promise is resolved. It is only shown if to is not provided.

Crochets

Aucun crochet n'est disponible pour AsyncLink.

Clés de traduction

Aucune clé de traduction n'est associée au composant AsyncLink.

Portes de sortie

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

Les options suivantes sont disponibles :

• Jetons de conception
• Transmission d'attributs HTML natifs
• Référence avec gestionnaires impératifs
• Propriété d'événement natif

Exemples

Consultez la section Utilisation pour en savoir plus sur la façon d'utiliser le composant AsyncLink et quand l'utiliser.

AsyncLink de base

Cet exemple montre l'utilisation de base du composant AsyncLink. Lorsque vous cliquez sur le lien, le rappel de la propriété onTrigger peut renvoyer true, false ou une promesse. Dans cet exemple, le message attribué « Patientez... » s'affiche, et au bout de deux secondes, ce message disparaît et affiche le texte « Soumis ».

import React, { useState, useEffect } from 'react';
import { AsyncLink } from '@jutro/router/';

export const BasicAsyncLink = () => {
  const [showMessage, setShowMessage] = useState(false);
  const [message, setMessage] = useState('Submit');

  const asyncMessage = "Wait..."; 

  useEffect(() => {
    let timerId;
    if (showMessage) {
      timerId = setTimeout(() => {
        setShowMessage(false);
        setMessage('Submited');
      }, 2000);
    }
    return () => clearTimeout(timerId); // Clear the timeout when the component unmounts or showMessage changes
  }, [showMessage]);

  function clickFunction() {
    setShowMessage(true);
    setMessage(asyncMessage);
  }

  return (
    <div>
      <AsyncLink
        message={asyncMessage}
        onTrigger={clickFunction}
        to="/test"
      >
        {message}
      </AsyncLink>
    </div>
  );
};

Messages AsyncLink

Vous pouvez utiliser les propriétés toMessage et failToMessage pour afficher des messages selon que la promesse retournée a réussi ou été rejetée.

En outre, vous pouvez utiliser la propriété failTo pour permettre une redirection vers un autre chemin en cas d'échec de la promesse.

import React, { useState } from 'react';
import { AsyncLink } from '@jutro/router/';

export const MessagesAsyncLink = () => {
  const [successLinkText, setSuccessLinkText] = useState('Success link');
  const [failureLinkText, setFailureLinkText] = useState('Failure link');

  const asyncMessage = "Wait...";
  const successMessage = "Action completed successfully!";
  const failureMessage = "Action failed. Please try again.";
  const timer = 2000;

  const handleSuccess = () => {
    setSuccessLinkText(asyncMessage);

    setTimeout(() => {
      setSuccessLinkText(successMessage);
      setTimeout(() => setSuccessLinkText('Success link'), timer);
    }, 2000);
  };

  const handleFailure = () => {
    setFailureLinkText(asyncMessage);

    setTimeout(() => {
      setFailureLinkText(failureMessage);
      setTimeout(() => setFailureLinkText('Failure link'), timer);
    }, 2000);
  };

  return (
    <div>
      <div>
        <AsyncLink
          message={asyncMessage}
          toMessage={successMessage}
          failToMessage={failureMessage}
          onTrigger={handleSuccess}
          to="/async-link#asynclink-messages"
        >
          {successLinkText}
        </AsyncLink>
      </div>
      <div>
        <AsyncLink
          message={asyncMessage}
          toMessage={successMessage}
          failToMessage={failureMessage}
          onTrigger={handleFailure}
          to="/async-link#asynclink-messages"
        >
          {failureLinkText}
        </AsyncLink>
      </div>
    </div>
  );
};

Journal des modifications

10.9.0

• Une nouvelle fonctionnalité d'opt-in a été introduite pour désactiver la publication automatique des événements pour le composant AsyncLink. Vous pouvez activer cette fonctionnalité en ajoutant JUTRO_DISABLE_AUTO_EVENTS_PUBLISHING=true au fichier .env dans la racine de votre application Jutro. Lorsque cette option est activée, les composants hérités ne publient plus d'événements par défaut. Pour en savoir plus sur les événements et sur la façon d'en créer de nouveaux, reportez-vous à la documentation relative aux événements.

10.1.0

• La prise en charge des jetons de conception a été ajoutée.