HOWTO · JavaScript

Comment utiliser le plein écran en JavaScript

Découvrez comment demander le mode plein écran pour un élément avec JavaScript, le quitter et réagir aux changements d'état du plein écran.

Sur cette page

Utilisez l’API plein écran du navigateur pour demander le passage en mode plein écran d’un élément choisi, en sortir avec document.exitFullscreen() et écouter fullscreenchange pour synchroniser l’interface. Appelez la méthode à la suite d’une action de l’utilisateur, comme un clic sur un bouton, et gérez sa promesse, car le navigateur peut refuser la demande.

Comprendre l’API plein écran

Le mode plein écran s’applique à un élément, par exemple un lecteur vidéo, un jeu, une présentation ou un conteneur de page. Le navigateur expose l’élément actif dans document.fullscreenElement ; cette propriété vaut null lorsqu’aucun élément n’est en plein écran. L’API plein écran est contrôlée par le navigateur : une demande peut être indisponible ou refusée selon l’action de l’utilisateur, le contexte de navigation et l’appareil.

Pour en savoir plus sur les méthodes et les événements, consultez la documentation de l’API plein écran sur MDN.

Méthode 1 : utiliser requestFullscreen() pour passer en mode plein écran

Sélectionnez l’élément à agrandir, puis appelez requestFullscreen() en réponse à un clic. L’API plein écran nécessite un contexte sécurisé, généralement HTTPS. Elle peut être indisponible si la page n’est pas dans un contexte sécurisé ou si la méthode est absente. Une demande peut également être refusée si elle ne fait pas suite à un geste de l’utilisateur ou si le contexte de navigation ou l’appareil ne l’autorise pas. Le fragment de page suivant est un exemple statique destiné au navigateur : son comportement dépend du navigateur et il ne constitue pas une sortie d’exécution.

<button id="enter-fullscreen">Enter full screen</button>
<button id="exit-fullscreen">Exit full screen</button>
<div id="player">Video or other content</div>
<p id="status" role="status"></p>
<script>
const enterButton = document.getElementById('enter-fullscreen');
const exitButton = document.getElementById('exit-fullscreen');
const player = document.getElementById('player');
const status = document.getElementById('status');

enterButton.addEventListener('click', async () => {
  if (typeof player.requestFullscreen !== 'function') {
    status.textContent = 'Full-screen mode is unavailable.';
    return;
  }

  try {
    await player.requestFullscreen();
  } catch (error) {
    status.textContent = 'The browser did not enter full-screen mode.';
  }
});

exitButton.addEventListener('click', async () => {
  if (!document.fullscreenElement) return;
  try {
    await document.exitFullscreen();
  } catch (error) {
    status.textContent = 'The browser did not exit full-screen mode.';
  }
});

document.addEventListener('fullscreenchange', () => {
  const active = document.fullscreenElement === player;
  status.textContent = active
    ? 'Player is full screen.'
    : document.fullscreenElement
      ? 'Another element is full screen.'
      : 'Full-screen mode has ended.';
  enterButton.disabled = active;
  exitButton.disabled = !document.fullscreenElement;
});
</script>

L’exemple pour navigateur ci-dessus utilise un véritable élément du DOM. L’exemple suivant utilise un substitut pour illustrer le déroulement de la promesse et le message renvoyé à la fin de la demande. Exécutez cet exemple :

const element = {
  requestFullscreen: () => Promise.resolve()
};

async function enterFullscreen(target) {
  await target.requestFullscreen();
  return 'Full-screen request completed';
}

enterFullscreen(element).then(console.log);
Full-screen request completed

Dans votre page, gardez l’appel dans le gestionnaire de clic afin qu’il fasse suite à un geste de l’utilisateur. Ne considérez pas les méthodes préfixées par un fournisseur comme une garantie de compatibilité : vérifiez la présence de la méthode standard et veillez à ce que le reste de l’interface reste utilisable si elle est absente ou si la promesse est rejetée. Si l’API semble indisponible, vérifiez également que la page est servie dans un contexte sécurisé, généralement HTTPS.

Méthode 2 : quitter le mode plein écran avec exitFullscreen()

Appelez document.exitFullscreen() pour quitter le mode plein écran. Cette méthode renvoie une promesse ; gérez donc son rejet comme pour le passage en plein écran. Les utilisateurs peuvent aussi quitter ce mode à l’aide des commandes du navigateur ou de l’appareil : l’interface doit refléter ce changement et ne pas supposer que seul son propre bouton de sortie peut mettre fin au mode.

Par exemple, dans une page web, associez un gestionnaire de clic à un bouton de sortie et appelez document.exitFullscreen() lorsque document.fullscreenElement n’est pas null. Interceptez le rejet de la promesse et affichez un message d’état utile. Cette description statique ne met pas en œuvre l’interaction exacte avec le navigateur.

Méthode 3 : gérer les événements de changement du mode plein écran

Écoutez l’événement fullscreenchange sur document. Il se déclenche lorsque l’état du mode plein écran change, y compris quand l’utilisateur quitte ce mode avec les commandes du navigateur. Lisez document.fullscreenElement à chaque déclenchement : une valeur différente de null désigne l’élément actuellement en plein écran, tandis que null indique que le mode a pris fin. Utilisez cet état pour actualiser le libellé des boutons, le texte d’état ou d’autres commandes. La pseudo-classe CSS :fullscreen permet de styliser un élément pendant que le navigateur l’affiche en plein écran.

Conclusion

Appelez requestFullscreen() sur l’élément choisi à la suite d’une action de l’utilisateur, gérez la promesse et utilisez document.exitFullscreen() si vous proposez une commande de sortie. Suivez fullscreenchange et document.fullscreenElement afin que l’interface réagisse aussi aux sorties déclenchées hors de la page. Le comportement peut varier selon le navigateur et l’appareil ; prévoyez donc un parcours utilisable sans mode plein écran.

FAQ

  1. Comment vérifier si un élément est en mode plein écran ? Vérifiez si document.fullscreenElement correspond à cet élément. Cette propriété vaut null lorsqu’aucun élément n’est actif.

  2. N’importe quel élément peut-il passer en mode plein écran ? L’API accepte un élément, mais les règles du navigateur et le contexte de navigation peuvent empêcher la réussite d’une demande. Lancez-la à la suite d’une action de l’utilisateur et gérez les échecs.

  3. Pourquoi requestFullscreen() peut-elle échouer ? La méthode peut être indisponible, notamment si la page n’est pas dans un contexte sécurisé, généralement HTTPS. La demande peut aussi ne pas faire suite à un geste de l’utilisateur ou être refusée pour le contexte de navigation ou l’appareil utilisé. Vérifiez la disponibilité de la méthode et gérez la promesse renvoyée.

  4. Comment styliser le contenu en plein écran ? Utilisez la pseudo-classe CSS :fullscreen pour appliquer des styles tant qu’un élément est en mode plein écran.