L’API Page Visibility (« visibilité de la page ») permet de savoir quand une page web est visible ou a le focus. Avec la navigation par onglets, il y a une probabilité raisonnable qu’une page web donnée soit en arrière-plan, donc masquée pour l’utilisateur. Quand celui-ci minimise la page ou bascule vers un autre onglet, l’API émet un évènement visibilitychange correspondant à la visibilité de la page. Vous pouvez détecter cet évènement et réaliser différentes actions ou modifier un comportement. Par exemple, si votre application web est en train de lire une vidéo, elle peut mettre cette dernière en pause au moment où l’utilisateur regarde un autre onglet, et reprendre la lecture quand la personne revient à l’onglet. L’utilisateur ne perd pas le fil de la vidéo et peut continuer à la regarder.

L’état de visibilité d’une <iframe> est le même que celui du document parent. Masquer l’iframe via une propriété CSS ne déclenche pas d’évènement de visibilité, ni ne change l’état du document contenu.

Avantages

L’API est particulièrement utile pour économiser des ressources. Elle donne aux développeurs l’opportunité de ne pas réaliser des tâches non nécessaires quand la page web est invisible.

Cas d’utilisation

Quelques exemples :

  • Un site comportant un carrousel qui ne doit pas passer à l’image suivante si l’utilisateur ne regarde pas la page.
  • Une application présentant un panneau d’informations, qui ne doit pas demander au serveur une mise à jour des données quand la page n’est pas visible.
  • Une page qui cherche à detecter quand elle est prerendered (pré-calculée), afin de tenir un compte précis du nombre de vues.
  • Un site qui cherche à désactiver les sons quand un appareil est en mode veille (l’utilisateur presse le bouton d’alimentation pour éteindre l’écran).

Historiquement, les développeurs ont utilisé des solutions de remplacement imparfaites pour détecter de tels changements. Par exemple, inscrire un gestionnaire onblur/onfocus sur la fenêtre est utile quand votre page n’est pas la page active, mais cela ne vous dit pas si votre page est masquée pour l’utilisateur. L’API Page Visibility corrige ce problème. (Lorsqu’on compare avec un gestionnaire onblur/onfocus sur la fenêtre, une différence notable est que la page ne devient pas cachée quand une autre fenêtre est rendue active et le navigateur perd le focus. Une page devient cachée seulement quand l’utilisateur bascule vers un autre onglet ou minimise la fenêtre du navigateur.)

Politiques de performance des pages en arrière-plan

En parallèle avec l’API Page Visibility, un certain nombre de politiques sont en place pour atténuer l’impact négatif sur les performances lié aux onglets en arrière-plan :

  • Les appels à Window.requestAnimationFrame() sont suspendus dans la plupart des navigateurs lorsqu’ils sont effectués dans un onglet en arrière-plan ou une <iframe> cachée, afin d’améliorer les performances et l’autonomie de la batterie.
  • Les timers tels que WindowOrWorkerGlobalScope.setTimeout sont retardés dans les onglets inactifs ou en arrière-plan pour aider à l’amélioration des performances. Voir Reasons for delays longer than specified pour plus de détails.
  • Les navigateurs modernes (Firefox 58+, Chrome 57+) ont mis en œuvre un retardement basé sur un budget pour les timeouts en arrière-plan. Cela place une limite supplémentaire sur la consommation de CPU des timers en arrière-plan. Cette limite opère de manière similaire dans tous les navigateurs modernes, avec les détails qui suivent :
    • Dans Firefox, les fenêtres d’onglets en arrière-plan ont chacune leur propre budget de temps en millisecondes — une valeur maximum et minimum de +50 ms et -150 ms, respectivement. Chrome est très similaire, excepté que le budget est spécifié en secondes.
    • Les fenêtres sont sujettes au retardement après 30 secondes, avec les mêmes règles de délai de retardement que spécifiées pour les timers (encore une fois, voir Reasons for delays longer than specified). Pour Chrome, cette valeur est de 10 secondes.
    • Les tâches de timers sont permises seulement quand le budget est non négatif.
    • Quand un timer a été exécuté, son temps d’exécution est retranché au budget de la fenêtre depuis laquelle le timer a été appelé.
    • Le budget regénère à un taux de 10 ms par seconde, sous Firefox et sous Chrome.
  • Certaines opérations sont exemptées de retardement :
    • Les applications qui jouent du son sont considérées comme en avant-plan, et donc ne sont pas retardées.
    • Les applications avec des connexions en temps réel (WebSockets et WebRTC), afin d’éviter que ces connexions soient fermées par timeout.
    • Les opérations IndexedDB.

Exemple

Voir l’exemple en direct (vidéo avec son).

Cet exemple, qui met la vidéo en pause quand vous basculez vers un autre onglet, et reprend la lecture quand vous y revenez, a été créé avec le code suivant :

// Set the name of the hidden property and the change event for visibility
var hidden, visibilityChange;
if (typeof document.hidden !== "undefined") { // Opera 12.10 and Firefox 18 and later support
  hidden = "hidden";
  visibilityChange = "visibilitychange";
} else if (typeof document.msHidden !== "undefined") {
  hidden = "msHidden";
  visibilityChange = "msvisibilitychange";
} else if (typeof document.webkitHidden !== "undefined") {
  hidden = "webkitHidden";
  visibilityChange = "webkitvisibilitychange";
}

var videoElement = document.getElementById("videoElement");

// If the page is hidden, pause the video;
// if the page is shown, play the video
function handleVisibilityChange() {
  if (document.hidden) {
    videoElement.pause();
  } else {
    videoElement.play();
  }
}

// Warn if the browser doesn't support addEventListener or the Page Visibility API
if (typeof document.addEventListener === "undefined" || typeof document.hidden === "undefined") {
  console.log("This demo requires a browser, such as Google Chrome or Firefox, that supports the Page Visibility API.");
} else {
  // Handle page visibility change
  document.addEventListener(visibilityChange, handleVisibilityChange, false);

  // When the video pauses, set the title.
  // This shows the paused
  videoElement.addEventListener("pause", function(){
    document.title = 'Paused';
  }, false);

  // When the video plays, set the title.
  videoElement.addEventListener("play", function(){
    document.title = 'Playing';
  }, false);

}

Propriétés

document.hidden Read only

Retourne true si la page est dans un état considéré comme masqué à l’utilisateur, et false dans le cas contraire.

document.visibilityState Read only

Une string représentant l’état de visibilité du document. Valeurs possibles :

  • visible : le contenu de la page peut être au moins partiellement visible. En pratique, cela signifie que la page est l’onglet actif d’une fenêtre non minimisée.
  • hidden : le contenu de la page n’est pas visible pour l’utilisateur. En pratique, cela signifie que le document est soit dans un onglet en arrière-plan, soit dans une fenêtre minimizée ; ou bien que l’écran de verrouillage de l’OS est actif.
  • prerender : le contenu de la page est en train d’être précalculé et n’est pas visible pour l’utilisateur (il est considéré masqué pour document.hidden). Le document peut être dans cet état initialement, mais ne passera jamais à cet état depuis une autre valeur. Note : le support des navigateurs est optionnel.
  • unloaded : la page est en train d’être déchargée de la mémoire. Note : le support des navigateurs est optionnel.
//startSimulation and pauseSimulation defined elsewhere
function handleVisibilityChange() {
  if (document.hidden) {
    pauseSimulation();
  } else  {
    startSimulation();
  }
}

document.addEventListener("visibilitychange", handleVisibilityChange, false);

document.onvisibilitychange

Un EventHandler représentant le code à appeler quand l’évènement visibilitychange est émis.

Spécifications

Spécification Statut Commentaire
Page Visibility (Second Edition) Recommendation Initial definition.

Compatibilité des navigateurs

Fonctionnalité Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Support de base 13 webkit
33
18 (18)[2] 10 12.10[1] 7
onvisibilitychange (Oui) 56 (56) (Oui) (Oui) (Oui)
Retardement à budget 57 58 (58) Pas de support (Oui) (Oui)
Fonctionnalité Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Support de base 5.0[3] 18.0 (18)[2] 10 12.10[1] 7[4]
onvisibilitychange (Oui) 56.0 (56) (Oui) (Oui) (Oui)
Retardement à budget Pas de support 58.0 (58) Pas de support (Oui) (Oui)

[1] N’émet pas d’évènement visibilitychange quand la fenêtre du navigateur est minimisée, ni ne passe hidden à true.

[2] De Firefox 10 à Firefox 51 inclus, cette propriété pouvait être utilisée avec le préfixe moz.

[3] Android 4.4 supporte cette fonctionnalité avec le préfixe webkit.

[4] À partir d’iOS 11.0.2, les valeurs sont incorrectes en mode standalone (quand vous pressez « ajouter à l’écran d’accueil ») et quand l’écran est verrouillé (le bouton d’alimentation a été pressé). La valeur pour hidden est false et visibilityState est visible.

Voir aussi

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : Watilin
 Dernière mise à jour par : Watilin,