Window : évènement beforeunload

Syntaxe

Utilisez le nom de l'évènement dans des méthodes comme addEventListener(), ou définissez une propriété de gestionnaire d'évènements.

addEventListener("beforeunload", (event) => { })

onbeforeunload = (event) => { }

Type d'évènement

Un objet BeforeUnloadEvent. Hérite de Event.

Notes d'utilisation

Pour déclencher l'affichage de la boîte de dialogue lorsque l'utilisateur·ice ferme ou navigue dans l'onglet, une fonction gestionnaire d'évènement beforeunload doit appeler preventDefault() sur l'objet évènement. Vous devez noter que les implémentations modernes :

• Exigent une activation persistante pour que la boîte de dialogue soit affichée. Autrement dit, le navigateur n'affichera la boîte de dialogue que si le cadre ou tout cadre intégré reçoit un geste ou une interaction de l'utilisateur·ice. Si l'utilisateur·ice n'a jamais interagi avec la page, il n'y a pas de données utilisateur à sauvegarder, donc aucun cas légitime pour la boîte de dialogue.
• N'affichent qu'une chaîne générique définie par le navigateur dans la boîte de dialogue affichée. Cela ne peut pas être contrôlé par le code de la page web.

L'évènement beforeunload présente certains problèmes :

• Il n'est pas déclenché de façon fiable, notamment sur les plateformes mobiles. Par exemple, l'évènement beforeunload n'est pas déclenché du tout dans le scénario suivant :

  1. Un·e utilisateur·ice mobile visite votre page.
  2. L'utilisateur·ice passe ensuite à une autre application.
  3. Plus tard, l'utilisateur·ice ferme le navigateur depuis le gestionnaire d'applications.

  Note : Il est recommandé d'utiliser l'évènement visibilitychange comme signal plus fiable pour la sauvegarde automatique de l'état de l'application, afin de contourner des problèmes comme ceux ci-dessus. Voir Ne perdez pas l'état utilisateur et application, utilisez la visibilité de page ^(angl.) pour plus de détails.

• Dans Firefox, beforeunload n'est pas compatible avec le cache arrière/avant ^(angl.) (bfcache) : c'est-à-dire que Firefox ne placera pas les pages dans le bfcache si elles ont des écouteurs beforeunload, ce qui est mauvais pour les performances.

Il est donc recommandé que les développeur·euse·s n'écoutent beforeunload que lorsque les utilisateur·ice·s ont des modifications non enregistrées afin que la boîte de dialogue mentionnée ci-dessus puisse être utilisée pour les avertir d'une perte de données imminente, et de retirer l'écouteur lorsque ce n'est pas nécessaire. Écouter beforeunload avec parcimonie peut minimiser l'impact sur les performances.

Alias du gestionnaire d'évènement

En plus de l'interface Window, la propriété de gestionnaire d'évènement onbeforeunload est également disponible sur les cibles suivantes :

• HTMLBodyElement
• HTMLFrameSetElement
• SVGSVGElement

Exemples

Dans l'exemple suivant, nous avons un champ de texte HTML <input> pour représenter des données qui pourraient être modifiées et nécessiter une sauvegarde :

<form>
  <input type="text" name="nom" id="nom" />
</form>

Notre JavaScript attache un écouteur d'évènement input à l'élément <input> qui écoute les changements de la valeur saisie. Lorsque la valeur est mise à jour avec une valeur non vide, un écouteur d'évènement beforeunload est attaché à l'objet Window.

Si la valeur redevient une chaîne de caractères vide (c'est-à-dire que la valeur est supprimée), l'écouteur d'évènement beforeunload est à nouveau retiré — comme mentionné plus haut dans les notes d'utilisation, l'écouteur doit être retiré lorsqu'il n'y a pas de données non enregistrées à signaler.

La fonction gestionnaire d'évènement beforeunload invoque event.preventDefault() pour déclencher la boîte de dialogue d'avertissement lorsque l'utilisateur·ice ferme ou navigue dans l'onglet. Nous avons également inclus event.returnValue = true dans la fonction gestionnaire afin que les navigateurs qui ne prennent pas en charge le mécanisme event.preventDefault() exécutent tout de même correctement la démonstration.

const gestionAvantDechargement = (event) => {
  // Recommandé
  event.preventDefault();

  // Inclus pour la compatibilité avec les anciennes versions, par exemple Chrome/Edge < 119
  event.returnValue = true;
};

const nomEntree = document.querySelector("#nom");

nomEntree.addEventListener("input", (event) => {
  if (event.target.value !== "") {
    window.addEventListener("beforeunload", gestionAvantDechargement);
  } else {
    window.removeEventListener("beforeunload", gestionAvantDechargement);
  }
});

Lorsque la valeur de l'élément <input> n'est pas vide, si vous essayez de fermer, de naviguer ou de recharger la page, le navigateur affiche la boîte de dialogue d'avertissement. Essayez-le :

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'interface BeforeUnloadEvent
• Évènements associés :
  • DOMContentLoaded
  • readystatechange
  • load
  • unload
• L'API Page Lifecycle ^(angl.) fournit des conseils plus utiles sur la gestion du comportement du cycle de vie des pages dans vos applications web.