Window : évènement unload

Syntaxe

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

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

onunload = (event) => { }

Type d'évènement

Un objet Event générique.

Alias des gestionnaires d'évènements

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

• HTMLBodyElement
• HTMLFrameSetElement
• SVGSVGElement

Notes d'utilisation

Les développeur·euse·s doivent éviter d'utiliser cet évènement.

Surtout sur mobile, l'évènement unload n'est pas déclenché de manière fiable. Par exemple, l'évènement unload 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.

De plus, l'évènement unload n'est pas compatible avec le cache arrière/avant ^(angl.) (bfcache), car de nombreuses pages utilisant cet évènement supposent que la page n'existe plus après le déclenchement de l'évènement. Pour remédier à cela, certains navigateurs (comme Firefox) ne placent pas les pages dans le bfcache si elles ont des écouteurs unload, ce qui est mauvais pour les performances.

Pour ces raisons, Chrome a cessé de déclencher les évènements unload par défaut ^(angl.). Une page qui dépend encore de unload peut se réactiver en utilisant la directive unload de l'en-tête Permissions-Policy.

À la place de unload, utilisez les évènements suivants, qui sont tous deux compatibles avec le bfcache :

• L'évènement visibilitychange est déclenché lorsque Document.visibilityState passe de visible à hidden, ou inversement. C'est le dernier évènement qui est déclenché de manière fiable, donc c'est le meilleur endroit pour sauvegarder l'état de l'application ou envoyer des données analytiques. Notez que visibilitychange est déclenché lorsque l'utilisateur·ice change d'onglet, quitte la page actuelle ou la ferme.
• L'évènement pagehide est déclenché lorsque le navigateur masque la page actuelle dans le processus de présentation d'une autre page à partir de l'historique de la session. Cela est utile si vous essayez spécifiquement de détecter que l'utilisateur·ice quitte la page. Cependant, comme unload, il n'est pas déclenché de manière fiable, surtout sur mobile, donc préférez visibilitychange lorsque c'est possible.

Par exemple, au lieu d'envoyer des données dans un écouteur unload :

window.addEventListener("unload", () => {
  navigator.sendBeacon("/log", analyticsData);
});

Envoyez-le lorsque la page devient cachée :

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") {
    navigator.sendBeacon("/log", analyticsData);
  }
});

Voir le guide de l'API Page Lifecycle ^(angl.) pour plus d'informations sur les problèmes associés à l'évènement unload.

Exemples

<!doctype html>
<html lang="fr">
  <head>
    <meta charset="UTF-8" />
    <title>Cadre parent</title>
    <script>
      window.addEventListener("beforeunload", (event) => {
        console.log("Je suis le premier 1er.");
      });
      window.addEventListener("unload", (event) => {
        console.log("Je suis le premier 3e.");
      });
    </script>
  </head>
  <body>
    <iframe src="child-frame.html"></iframe>
  </body>
</html>

Ci-dessous, le contenu de child-frame.html :

<!doctype html>
<html lang="fr">
  <head>
    <meta charset="UTF-8" />
    <title>Cadre enfant</title>
    <script>
      window.addEventListener("beforeunload", (event) => {
        console.log("Je suis le premier 2e.");
      });
      window.addEventListener("unload", (event) => {
        console.log("Je suis le premier 4e et dernier…");
      });
    </script>
  </head>
  <body>
    ☻
  </body>
</html>

Lorsque le cadre parent est déchargé, les évènements sont déclenchés dans l'ordre décrit par les messages console.log().

Spécifications

Compatibilité des navigateurs

Voir aussi

• Évènements associés : DOMContentLoaded, readystatechange, load
• Décharger les documents — décharger un document ^(angl.)
• L'évènement visibilitychange
• Ne perdez pas l'état de l'utilisateur·ice et de l'application, utilisez la visibilité de la page ^(angl.) explique en détail pourquoi vous devez utiliser visibilitychange et non beforeunload/unload.
• L'API Page Lifecycle ^(angl.) donne des conseils sur les bonnes pratiques pour gérer le comportement du cycle de vie des pages dans vos applications web.
• PageLifecycle.js ^(angl.) : une bibliothèque JavaScript qui gère les incohérences entre navigateurs dans le comportement du cycle de vie des pages.
• Cache arrière/avant ^(angl.) explique ce qu'est le cache arrière/avant et ses implications pour divers évènements du cycle de vie des pages.