Le système de modales

Le système de modales fait partie du framework. Il gère l’affichage des boîtes de dialogue modales, des avertissements et d’autres affichages similaires. Son objectif principal est de coordonner les modales entre différentes applications afin que la modale la plus haute soit visible pendant que les modales ouvertes précédemment restent montées mais masquées dans la pile.

Pour utiliser le système de modales, votre application doit d’abord enregistrer la modale comme décrit ci-dessous. Une fois la modale enregistrée, appelez showModal avec le nom de la modale, et le framework l’affichera pour vous.

Utilisation

Implémentation de la modale

ModalHeader et ModalBody doivent être au niveau supérieur du composant de modale et enveloppés dans un React.Fragment.


import { Button, ModalBody, ModalFooter, ModalHeader } from '@carbon/react';
 
interface DeleteItemModalProps {
  close: () => void;
  itemName: string;
}
 
export default function DeleteItemModal({ close, itemName }: DeleteItemModalProps) {
  return (
    <>
      <ModalHeader closeModal={close} title="Supprimer l'élément" />
      <ModalBody>
        <p>Voulez-vous vraiment supprimer {itemName}?</p>
      </ModalBody>
      <ModalFooter>
        <Button kind="secondary" onClick={close}>
          Annuler
        </Button>
        <Button kind="danger">Supprimer</Button>
      </ModalFooter>
    </>
  );
}

Si vous n’enveloppez pas votre modale dans un React Fragment, le corps de la modale ne défilera pas correctement verticalement.

Enregistrement de la modale

Enregistrez la modale par son nom dans la propriété modals de routes.json et exportez-la dans le fichier index.ts de l’application qui la définit. Le name doit se terminer par -modal. Par exemple, si le nom de la modale est delete-condition, le name doit être delete-condition-modal. Le component doit être le nom du composant qui rend la modale.

routes.json


"modals": [
	{
	  "name": "your-modal-name-modal",
	  "component": "modalComponentName"
	}
]

index.ts


import { getAsyncLifecycle } from '@openmrs/esm-framework';
 
export const modalComponentName = getAsyncLifecycle(
  () => import('./path-to-the-modal-component/modal-component'),
  options,
);

Du code plus ancien peut encore enregistrer des composants de modale comme extensions et les lancer par nom d’extension. Le framework utilise encore ce chemin de repli et affiche un avertissement de dépréciation, mais les nouvelles modales doivent toujours utiliser la section modals dans routes.json.

Déclenchement de la modale

Enfin, vous pouvez déclencher votre modale en appelant showModal avec toutes les props que vous devez transmettre à la modale. La fonction retournée par showModal peut être appelée pour “dispose” la modale, c’est-à-dire la fermer de force. Le framework transmet aussi cette même fonction à la modale avec la prop close.


const close = showModal('your-modal-name-modal', {
  itemName: "Exemple d'élément",
  // autres props à transmettre au composant de modale
});

Passez la prop close injectée à l’en-tête Carbon avec closeModal={close}.

Considérations importantes

Empilement des modales

Le système de modales prend en charge l’empilement de plusieurs modales. Quand une nouvelle modale est ouverte alors qu’une autre est déjà affichée, la nouvelle apparaît au-dessus et la précédente reste dans la pile, masquée. Fermer la modale du dessus révèle celle qui se trouve dessous. Cela permet des workflows de modales imbriquées sans perdre le contexte.

Le callback `onClose`

La fonction showModal accepte un troisième paramètre optionnel, le callback onClose, appelé quand la modale est fermée:


const dispose = showModal('your-modal-name-modal', {
  itemName: "Exemple d'élément",
  // autres props
}, () => {
  // Ce callback est appelé quand la modale est fermée
  console.log('Modal was closed');
});

Taille de la modale

Vous pouvez contrôler la taille de la modale en passant une prop size. Les tailles disponibles sont 'xs', 'sm', 'md' par défaut et 'lg':


const dispose = showModal('your-modal-name-modal', {
  itemName: "Exemple d'élément",
  size: 'sm', // ou 'xs', 'md', 'lg'
});

Gestion des erreurs

Si vous tentez d’afficher une modale qui n’a pas été enregistrée, le framework signale une erreur dans la console mais ne lance pas d’exception. Assurez-vous que votre modale est correctement enregistrée dans routes.json avant d’appeler showModal.

Comportements automatiques

Le système de modales gère automatiquement plusieurs comportements:

Verrouillage du défilement du body: quand une modale est ouverte, le défilement de la page est automatiquement verrouillé pour empêcher le défilement de l’arrière-plan.
Gestion de la touche ESC: appuyer sur ESC ferme la modale la plus haute.
Visibilité de la pile: seule la modale au sommet est visible; les modales ouvertes précédemment restent montées mais masquées jusqu’à la fermeture de celle du dessus.

La prop `close`

Le framework ajoute automatiquement une prop close à votre composant de modale. C’est la fonction dispose retournée par showModal. Utilisez cette prop pour fermer la modale depuis le composant, et transmettez-la à l’en-tête Carbon avec closeModal={close}.

Vous pouvez encore voir du code plus ancien transmettre une prop personnalisée closeModal via showModal. Cela fonctionne, mais c’est inutile sauf si l’API d’un composant existant attend explicitement une prop portant ce nom.