<dialog> : l'élément de boîte de dialogue

Cet élément inclut les attributs universels.

open

Cet attribut indique que la boîte de dialogue est active et peut être utilisée de façon interactive. Si l'attribut n'est pas renseigné, la boîte de dialogue ne doit pas être affichée. Il est recommandé d'utiliser les méthodes .show() ou .showModal() afin d'afficher les boîtes de dialogue, plutôt que l'attribut open. Si un élément <dialog> est ouvert à l'aide de l'attribut open, il s'agira d'une boîte non-modale.

Note : Bien qu'il soit possible de basculer entre l'état ouvert et l'état fermé des boîtes de dialogue ne bloquant pas l'interraction en modifiant la présence de l'attribut open, cette approche n'est pas recommandée.

• Les éléments <form> peuvent fermer un dialogue s'ils possèdent l'attribut method="dialog" ou si le bouton utilisé pour soumettre le formulaire a l'attribut formmethod="dialog". Lorsqu'un tel formulaire est soumis, le dialogue se ferme avec sa propriété returnValue définie sur la value (valeur) du bouton qui a été utilisé pour soumettre le formulaire.
• Le pseudo-élément CSS ::backdrop peut être utilisé pour créer un style derrière un élément <dialog> lorsque le dialogue est affiché avec HTMLDialogElement.showModal(). Par exemple, pour atténuer le contenu inaccessible derrière la boîte de dialogue modale.
• L'attribut autofocus peut être ajouté à l'élément avec lequel la personne est censée interagir immédiatement après l'ouverture d'une boîte de dialogue modale. S'il n'y a pas d'élément impliquant une interaction immédiate, l'attribut autofocus peut être ajouté à l'élément <dialog> lui-même.

Cet exemple montre comment créer une boîte de dialogue non-modale en utilisant uniquement du HTML. Grâce à l'attribut booléen open de l'élément <dialog>, la boîte de dialogue apparaît ouverte au chargement de la page. Le dialogue peut être fermé en cliquant sur le bouton "OK" parce que l'attribut method de l'élément <form> est fixé à "dialog". Dans ce cas, aucun JavaScript n'est nécessaire pour fermer le formulaire.

<dialog open>
  <p>Salutations, à tous et à toutes !</p>
  <form method="dialog">
    <button>OK</button>
  </form>
</dialog>

Résultat

Cette boîte de dialogue est initialement ouverte en raison de la présence de l'attribut open. Les boîtes de dialogue affichées à l'aide de l'attribut open sont non-modales. Vous pouvez remarquer qu'après avoir cliqué sur « OK », la boîte de dialogue est fermée, laissant le cadre de résultat vide. Lorsque la boîte de dialogue est fermée, aucune méthode n'est prévue pour la rouvrir. C'est pourquoi la méthode préférée pour afficher les boîtes de dialogue non-modales consiste à utiliser la méthode HTMLDialogElement.show(). Il est possible de basculer l'affichage de la boîte de dialogue en ajoutant ou en supprimant l'attribut booléen open, mais ce n'est pas la pratique recommandée.

Cet exemple montre une boîte de dialogue modale avec un arrière-plan. La méthode .showModal() ouvre la boîte de dialogue modale lorsque le bouton « Afficher la fenêtre » est activé. La boîte de dialogue peut être fermée en appuyant sur la touche Échap ou via la méthode .close() lorsque le bouton « Fermer » de la boîte de dialogue est activé.

Lorsqu'une boîte de dialogue s'ouvre, le navigateur donne, par défaut, la priorité au premier élément qui peut l'être dans la boîte de dialogue. Dans cet exemple, l'attribut autofocus est appliqué au bouton « Fermer », lui donnant la priorité à l'ouverture de la boîte de dialogue, car c'est l'élément avec lequel nous nous attendons à ce que la personne interagisse immédiatement après l'ouverture de la boîte de dialogue.

HTML

<dialog>
  <button autofocus>Fermer</button>
  <p>Cette boîte de dialogue modale a un arrière-plan festif !</p>
</dialog>
<button>Afficher la fenêtre</button>

CSS

Nous pouvons styliser l'arrière-plan du dialogue en utilisant le pseudo-élément ::backdrop.

::backdrop {
  background-image: linear-gradient(
    45deg,
    magenta,
    rebeccapurple,
    dodgerblue,
    green
  );
  opacity: 0.75;
}

JavaScript

Le dialogue est ouvert de façon modale en utilisant la méthode .showModal() et est fermé en utilisant la méthode .close().

const dialog = document.querySelector("dialog");
const showButton = document.querySelector("dialog + button");
const closeButton = document.querySelector("dialog button");

// Le bouton "Afficher la fenêtre" ouvre le dialogue
showButton.addEventListener("click", () => {
  dialog.showModal();
});

// Le bouton "Fermer" ferme le dialogue
closeButton.addEventListener("click", () => {
  dialog.close();
});

Résultat

Lorsque la boîte de dialogue modale est affichée, elle apparaît au-dessus de toutes les autres boîtes de dialogue éventuellement présentes. Tout ce qui se trouve en dehors de la boîte de dialogue modale est inerte et les interactions en dehors de cette dernière sont bloquées. Remarquez que lorsque la boîte de dialogue est ouverte, à l'exception d'elle-même, il n'est pas possible d'interagir avec le document ; le bouton « Afficher la fenêtre » est en grande partie masqué par l'arrière-plan presque opaque de la boîte de dialogue et est inerte.

Cet exemple illustre comment utiliser la valeur de retour, fournie par returnValue et comment fermer un dialogue modal en utilisant un formulaire. Par défaut, la valeur de retour est la chaîne vide ou la valeur du bouton qui soumet le formulaire dans l'élément <dialog>, s'il y en a un.

Cet exemple ouvre une boîte de dialogue modale lorsque le bouton « Mettre à jour les détails » est activé. La boîte de dialogue contient un formulaire avec un élément <select> et deux éléments <button>, dont la valeur par défaut est type="submit". Un écouteur d'évènement met à jour la valeur du bouton « Confirmer » lorsque l'option sélectionnée change. Si le bouton « Confirmer » est activé pour fermer la boîte de dialogue, la valeur actuelle du bouton est la valeur de retour. Si la boîte de dialogue est fermée en appuyant sur le bouton « Annuler », la valeur de retour returnValue est cancel.

Lorsque le dialogue est fermé, la valeur de retour est affichée sous le bouton « Mettre à jour les détails ». Si le dialogue est fermé en appuyant sur la touche Échap, la valeur de retour returnValue n'est pas mise à jour et l'événement close ne se produit pas, ce qui signifie que le texte dans l'élément <output> n'est pas mis à jour.

HTML

<!-- Boîte de dialogue contextuelle simple contenant un formulaire -->
<dialog id="favDialog">
  <form method="dialog">
    <p>
      <label>
        Animal préféré :
        <select>
          <option>Choisissez…</option>
          <option>Crevette en saumure</option>
          <option>Panda rouge</option>
          <option>Singe-araignée</option>
        </select>
      </label>
    </p>
    <menu>
      <button value="cancel">Annuler</button>
      <button id="confirmBtn" value="default">Confirmer</button>
    </menu>
  </form>
</dialog>
<p>
  <button id="showDialog">Mettre à jour les détails</button>
</p>
<output></output>

JavaScript

const showButton = document.getElementById("showDialog");
const favDialog = document.getElementById("favDialog");
const outputBox = document.querySelector("output");
const selectEl = favDialog.querySelector("select");
const confirmBtn = favDialog.querySelector("#confirmBtn");

// Le bouton « Mettre à jour les détails » ouvre la modale <dialog>
showButton.addEventListener("click", () => {
  favDialog.showModal();
});

// L'entrée « Animal préféré » définit la valeur du bouton d'envoi.
selectEl.addEventListener("change", (e) => {
  confirmBtn.value = selectEl.value;
});

// Le bouton « Annuler » ferme la boîte de dialogue sans la soumettre en raison de l'attribut [formmethod="dialog"], ce qui déclenche un événement de fermeture.
favDialog.addEventListener("close", (e) => {
  outputBox.value =
    favDialog.returnValue === "default"
      ? "Pas de valeur retournée."
      : `Valeur retournée : ${favDialog.returnValue}.`; // Vérifie la présence de "default" au lieu d'une chaîne vide
});

// Empêchez le bouton « Confirmer » de soumettre le formulaire par défaut et fermez la boîte de dialogue avec la méthode `close()`, qui déclenche l'événement "close".
confirmBtn.addEventListener("click", (event) => {
  event.preventDefault(); // Nous ne voulons pas soumettre ce faux formulaire
  favDialog.close(selectEl.value); // Il faut envoyer la valeur du sélecteur ici.
});

Résultat

Cet exemple présente les trois méthodes suivantes pour fermer les boîtes de dialogue modales :

• En soumettant le formulaire dans la boîte de dialogue à l'aide de la méthode dialog (comme dans l'exemple n'utilisant que du HTML)
• En appuyant sur la touche Échap.
• En appelant la méthode HTMLDialogElement.close() (comme dans l'exemple de création d'une boîte modale). Dans cet exemple, le bouton « Annuler » ferme la boîte de dialogue via la méthode de formulaire dialog et le bouton « Confirmer » ferme la boîte de dialogue via la méthode HTMLDialogElement.close().

Le bouton « Annuler » comprend l'attribut formmethod="dialog", qui remplace la méthode par défaut GET de l'élément <form>. Lorsque la méthode d'un formulaire est dialog, l'état du formulaire est sauvegardé mais non soumis, et la boîte de dialogue est fermée.

Sans action, la soumission du formulaire via la méthode par défaut GET entraîne le rechargement de la page. Nous utilisons JavaScript pour empêcher la soumission et fermer le dialogue avec les méthodes event.preventDefault() et HTMLDialogElement.close(), respectivement.

Il est important de prévoir un mécanisme de fermeture dans chaque élément <dialog>. La touche Échap ne ferme pas les dialogues non modaux par défaut, et l'on ne peut pas non plus supposer que la personne aura accès à un clavier physique (par exemple, une personne utilisant un écran tactile sans accès à un clavier).

Lors de l'implémentation d'une fenêtre de dialogue, il est important de considérer l'endroit le plus approprié pour placer le point de concentration (ou « focus ») de la personne. Lorsque l'on utilise HTMLDialogElement.showModal() pour ouvrir un <dialog>, le « focus » est mis sur le premier élément imbriqué focalisable. Le fait d'indiquer explicitement l'emplacement initial du « focus » en utilisant l'attribut autofocus permet de s'assurer que le « focus » initial est placé sur l'élément considéré comme le meilleur emplacement initial pour un dialogue particulier. En cas de doute, comme il n'est pas toujours possible de savoir où le « focus » initial peut être placé dans un dialogue, en particulier dans les cas où le contenu d'un dialogue est rendu dynamiquement lorsqu'il est invoqué, l'élément <dialog> lui-même peut fournir le meilleur placement du « focus » initial.

Veillez à ce qu'un mécanisme soit prévu pour permettre de fermer la boîte de dialogue. La meilleure façon de s'assurer que toutes les personnes peuvent fermer la boîte de dialogue est d'inclure un bouton explicite à cet effet, tel qu'un bouton de confirmation, d'annulation ou de fermeture.

Par défaut, une boîte de dialogue invoquée par la méthode showModal() peut être fermée en appuyant sur la touche Échap. Une boîte de dialogue non-modale ne se ferme pas par la touche Échap par défaut, et selon ce que représente la boîte de dialogue non-modale, ce comportement n'est peut-être pas souhaitable Les utilisatrices et utilisateurs de clavier s'attendent à ce que la touche Échap ferme les boîtes de dialogue modales ; veillez à ce que ce comportement soit implémenté et maintenu. Si plusieurs boîtes de dialogue modales sont ouvertes, l'appui sur la touche Échap ne doit fermer que la dernière boîte de dialogue affichée. Lorsque l'on utilise <dialog>, ce comportement est fourni par le navigateur.

Bien que les boîtes de dialogue puissent être créées à l'aide d'autres éléments, l'élément natif <dialog> offre des caractéristiques d'utilisation et d'accessibilité qui doivent être reproduites si vous utilisez d'autres éléments dans un but similaire. Si vous créez une implémentation de dialogue personnalisée, assurez-vous que tous les comportements par défaut attendus sont pris en charge et que les recommandations d'étiquetage appropriées sont suivies.

L'élément <dialog> est exposé par les navigateurs d'une manière similaire aux dialogues personnalisés qui utilisent l'attribut ARIA role="dialog". Les éléments <dialog> invoqués par la méthode showModal() ont implicitement aria-modal="true", alors que les éléments <dialog> invoqués par la méthode show() ou affichés en utilisant l'attribut open ou en changeant la propriété CSS display par défaut d'un élément HTML <dialog> sont exposés en tant que [aria-modal="false"]. Lors de l'implémentation de dialogues modaux, tout ce qui n'est pas le <dialog> et son contenu doit être rendu inerte en utilisant l'attribut HTML global inert. Lorsque l'on utilise <dialog> avec la méthode HTMLDialogElement.showModal(), ce comportement est fourni par le navigateur.

• L'interface HTMLDialogElement
• L'évènement close
• L'évènement cancel
• La propriété open de l'interface HTMLDialogElement
• L'attribut HTML universel inert
• Le pseudo-élément ::backdrop
• Guide sur les formulaires HTML