Element : méthode requestFullscreen()

Syntaxe

requestFullscreen()
requestFullscreen(options)

Paramètres

options Facultatif

Un objet qui contrôle le comportement de la transition vers le mode plein écran. Les options disponibles sont :

keyboardLock Facultatif

Contrôle le mode de verrouillage du clavier sélectionné.

"none"

Aucun verrouillage du clavier n'est appliqué. C'est le mode par défaut.

"browser"

Le mode de verrouillage du clavier du navigateur est appliqué. Dans ce mode, le navigateur transmet les évènements clavier à l'application qui est normalement gérée par le code du navigateur ou du système. Les applications doivent intercepter les évènements pour les touches et combinaisons de touches qu'elles souhaitent utiliser, et appeler preventDefault() pour annuler toute action par défaut.

Notez que certains navigateurs peuvent désactiver l'action par défaut pour certaines touches, comme la touche normalement utilisée pour quitter le mode plein écran ; ce n'est pas garanti, donc vous devez toujours appeler preventDefault(). Les navigateurs sont également encouragés à fournir un mécanisme pour quitter le mode plein écran avec le verrouillage du clavier.

Pour plus d'informations, voir la section Verrouillage du clavier ci-dessous.

navigationUI Facultatif

Contrôle l'affichage ou non de l'interface de navigation lorsque l'élément est en mode plein écran. La valeur par défaut est "auto", ce qui indique que le navigateur doit décider quoi faire.

"hide"

L'interface de navigation du navigateur est masquée et l'ensemble des dimensions de l'écran est alloué à l'affichage de l'élément.

"show"

Le navigateur affiche les contrôles de navigation de la page et éventuellement d'autres éléments de l'interface utilisateur ; les dimensions de l'élément (et la taille perçue de l'écran) sont ajustées pour laisser de la place à cette interface utilisateur.

"auto"

Le navigateur choisit quelle des options ci-dessus appliquer. C'est la valeur par défaut.

screen Facultatif

Définit sur quel écran vous souhaitez mettre l'élément en mode plein écran. Cela prend un objet ScreenDetailed comme valeur, représentant l'écran choisi.

Valeur de retour

Une promesse (Promise) qui est résolue avec une valeur undefined lorsque la transition vers le mode plein écran est terminée, ou qui est rejetée avec une exception.

Exceptions

En cas d'erreur, la promesse (Promise) retournée est rejetée avec l'une des valeurs suivantes :

TypeError

L'exception TypeError peut être levée dans l'une des situations suivantes :

• Le document contenant l'élément n'est pas entièrement actif ; c'est-à-dire qu'il n'est pas le document actif actuel.
• L'élément n'est pas contenu par un document.
• L'élément n'est pas autorisé à utiliser la fonctionnalité fullscreen, soit en raison de la configuration de la Politique d'autorisations ou d'autres fonctionnalités de contrôle d'accès.
• L'élément et son document sont le même nœud.
• L'élément est une fenêtre contextuelle qui est déjà affichée avec HTMLElement.showPopover().

NotSupportedError DOMException

Le paramètre options.keyboardLock passé n'est pas pris en charge par le navigateur.

Description

La méthode requestFullscreen() envoie une requête asynchrone pour afficher l'élément en mode plein écran.

Cette méthode nécessite une autorisation.

• Si l'autorisation d'entrer en mode plein écran est accordée, la promesse (Promise) retournée est résolue et l'élément reçoit un évènement fullscreenchange pour l'informer qu'il est maintenant en mode plein écran.

• Si l'autorisation est refusée, la promesse est rejetée et l'élément reçoit à la place un évènement fullscreenerror.

• Si l'élément a été détaché du document d'origine, alors c'est le document qui reçoit ces évènements à la place.

Éléments compatibles

• Un élément que vous souhaitez afficher en mode plein écran doit répondre à un petit nombre d'exigences simples :

• Il doit s'agir de l'un des éléments HTML standard ou de <svg> ou de <math>.

• Il ne doit pas s'agir d'un élément HTML <dialog>.

• Il doit être soit situé dans le document de niveau supérieur, soit dans un <iframe> auquel l'attribut allowfullscreen est appliqué.

De plus, toutes politiques de permissions (Permissions-Policy) définies doivent permettre l'utilisation de la fonctionnalité fullscreen.

Détecter l'activation du mode plein écran

Vous pouvez déterminer si votre tentative de passage en mode plein écran a réussi ou non en utilisant la promesse (Promise) retournée par requestFullscreen(), comme le montre les exemples ci-dessous.

Pour savoir quand un autre code a activé ou désactivé le mode plein écran, vous devez établir des écouteurs pour l'évènement fullscreenchange sur le Document. Il est également important d'écouter fullscreenchange pour savoir, par exemple, quand l'utilisateur·ice active manuellement le mode plein écran, ou quand l'utilisateur·ice change d'application, ce qui entraîne la sortie temporaire de votre application du mode plein écran.

Verrouillage du clavier

Le verrouillage du clavier permet à une application en plein écran d'intercepter et de gérer certaines touches et combinaisons de touches qui sont autrement exclusivement gérées par le navigateur ou le système d'exploitation sous-jacent. Cela peut améliorer l'expérience utilisateur pour les jeux, par exemple, en permettant à la touche Esc d'être utilisée comme touche de menu au lieu de quitter le mode plein écran. Cela peut également être utile pour des applications telles que le contrôle à distance d'un ordinateur, où vous souhaitez que presque tous les évènements clavier soient transmis à l'ordinateur distant.

Le verrouillage du clavier est activé en passant une valeur de mode de verrouillage du clavier de "browser" au paramètre options.keyboardLock lors de l'activation du mode plein écran. Lorsque le verrouillage du clavier est actif en mode plein écran, le navigateur redirige « beaucoup plus » d'évènements clavier vers l'application — l'ensemble précis des touches dépend du navigateur. L'application web doit gérer l'évènement en appelant d'abord preventDefault() pour annuler son action par défaut. Certaines combinaisons de touches sont utilisées pour le contrôle du système ou présentent des risques pour la vie privée, et ne peuvent donc pas être interceptées et désactivées à l'aide de ce mécanisme (par exemple, Ctrl+Alt+Suppr sous Windows).

Notez que certains navigateurs désactivent toujours l'action par défaut pour la touche Esc lorsque le verrouillage du clavier est actif, de sorte que l'appui sur cette touche ne quitte pas automatiquement le mode plein écran. Cependant, comme cela n'est pas garanti, vous devez toujours appeler preventDefault() pour empêcher les pressions sur la touche Esc de quitter le mode plein écran. De manière générale, vous ne pouvez pas supposer que l'action par défaut pour un évènement clavier quelconque est désactivée par défaut.

Les navigateurs sont censés fournir un mécanisme alternatif pour quitter le mode plein écran lorsque le verrouillage du clavier est activé. La plupart des navigateurs utilisent la touche Esc pour quitter le mode plein écran normal, et un appui long sur la touche Esc pour quitter le verrouillage du clavier. Le verrouillage du clavier est désactivé lorsque le navigateur quitte le mode plein écran.

Considérations de sécurité

Une activation utilisateur transitoire est requise. L'utilisateur·ice doit interagir avec la page ou un élément de l'interface utilisateur pour que cette fonctionnalité fonctionne.

Le mode plein écran est contrôlé par la directive fullscreen des politiques d'autorisations.

La liste blanche par défaut pour screen-wake-lock est self. Ceci permet l'utilisation du mode plein écran dans des frames imbriquées de même origine mais l'empêche dans le contenu tiers. L'utilisation par des tiers peut être activée par le serveur en définissant d'abord l'en-tête Permissions-Policy pour accorder l'autorisation à une origine tierce particulière.

Permissions-Policy: fullscreen=(self b.example.com)

Ensuite, l'attribut allow="fullscreen" doit être ajouté à l'élément conteneur de la frame pour les sources provenant de cette origine :

<iframe src="https://b.example.com" allow="fullscreen"></iframe>

La permission fullscreen de l'API Permissions peut être utilisée pour tester si l'accès à l'utilisation du mode plein écran est granted, denied ou prompt (nécessite la reconnaissance d'une invite par l'utilisateur·ice).

Exemples

Demander le mode plein écran

Cet exemple bascule l'élément <video> en mode plein écran et en sort lorsque les touches Enter ou Shift + F sont enfoncées. Le script vérifie si le document est actuellement en mode plein écran à l'aide de document.fullscreenElement. Si le document est en mode plein écran, il appelle document.exitFullscreen() pour en sortir. Sinon, il appelle requestFullscreen() sur l'élément <video> :

const video = document.querySelector("video");

document.addEventListener("keydown", (event) => {
  // Notez que "F" est sensible à la casse (majuscule) :
  if (event.key === "Enter" || event.key === "F") {
    // Vérifie si nous sommes en mode plein écran
    if (document.fullscreenElement) {
      document.exitFullscreen();
      return;
    }
    // Sinon, entrer en mode plein écran
    video.requestFullscreen().catch((err) => {
      console.error(
        `Erreur lors de l'activation du mode plein écran : ${err.message}`,
      );
    });
  }
});

<p>
  L'élément vidéo ci-dessous montre un accéléré d'une fleur en train d'éclore.
  Vous pouvez basculer le mode plein écran en utilisant
  <kbd>Enter</kbd> ou <kbd>Shift</kbd> + <kbd>F</kbd> («&nbsp;F&nbsp;»
  majuscule). Le document intégré doit avoir
  <a href="https://developer.mozilla.org/fr/docs/Web/API/Element/focus_event">
    la sélection
  </a>
  pour que l'exemple fonctionne.
</p>

<video controls loop src="/shared-assets/videos/flower.mp4" width="420"></video>

body {
  font-family:
    "Benton Sans", "Helvetica Neue", "Helvetica", "Arial", sans-serif;
  margin: 2em;
}

video::backdrop {
  background-color: #444488;
}
button {
  display: block;
}
kbd {
  border: 2px solid #cdcdcd;
  border-radius: 3px;
  box-shadow: inset 0 -1px 0 0 #cdcdcd;
  font-size: 0.825rem;
  padding: 0.25rem;
}

Utiliser le verrouillage du clavier

Cet exemple est presque identique à l'exemple précédent, sauf que nous demandons que le mode plein écran soit activé avec le verrouillage du clavier.

JavaScript

const video = document.querySelector("video");

Le code modifié de l'écouteur d'évènements clavier est montré ci-dessous.

La première différence est que nous gérons l'évènement pour la touche Esc en mode plein écran, en appelant event.preventDefault() pour désactiver l'action par défaut (qui est de quitter le mode plein écran).

Comme précédemment, nous appelons requestFullscreen() si Enter ou Shift+F sont enfoncées lorsque nous ne sommes pas en mode plein écran. Cependant, dans ce cas, nous passons l'option keyboardLock avec la valeur "browser".

document.addEventListener("keydown", (event) => {
  // Vérifie si nous sommes en mode plein écran
  if (document.fullscreenElement) {
    // Annule la sortie avec la touche Échap
    if (event.key === "Escape") {
      event.preventDefault();
      // Faites ce que vous voulez lorsque la touche Échap est enfoncée
    }
  } else if (event.key === "Enter" || event.key === "F") {
    // Passe en mode plein écran si <kbd>Enter</kbd> ou <kbd>F</kbd> sont
    // enfoncées et que nous ne sommes pas déjà en mode plein écran.
    // Notez que "F" est sensible à la casse (majuscule).
    video.requestFullscreen({ keyboardLock: "browser" }).catch((err) => {
      console.error(
        `Erreur lors de l'activation du mode plein écran : ${err.message}`,
      );
    });
  }
});

<p>
  L'élément vidéo ci-dessous montre un accéléré d'une fleur en train d'éclore.
  Vous pouvez basculer le mode plein écran en utilisant
  <kbd>Enter</kbd> ou <kbd>Shift</kbd> + <kbd>F</kbd> («&nbsp;F&nbsp;»
  majuscule). Le document intégré doit avoir
  <a href="https://developer.mozilla.org/fr/docs/Web/API/Element/focus_event">
    la sélection
  </a>
  pour que l'exemple fonctionne.
</p>

<video controls loop src="/shared-assets/videos/flower.mp4" width="420"></video>

body {
  font-family:
    "Benton Sans", "Helvetica Neue", "Helvetica", "Arial", sans-serif;
  margin: 2em;
}

video::backdrop {
  background-color: #444488;
}
button {
  display: block;
}
kbd {
  border: 2px solid #cdcdcd;
  border-radius: 3px;
  box-shadow: inset 0 -1px 0 0 #cdcdcd;
  font-size: 0.825rem;
  padding: 0.25rem;
}

Résultat

Sélectionnez le cadre et appuyez sur Shift+F. Lorsque la page s'affiche en plein écran, notez la notification temporaire en haut de la page qui explique comment quitter le mode plein écran.

Utiliser navigationUI

Dans cet exemple, l'ensemble du document est placé en mode plein écran en appelant requestFullscreen() sur le Document.documentElement du document, qui est l'élément racine <html> du document.

let elem = document.documentElement;

elem
  .requestFullscreen({ navigationUI: "show" })
  .then(() => {})
  .catch((err) => {
    alert(
      `Une erreur s'est produite lors de la tentative de passage en mode plein écran : ${err.message} (${err.name})`,
    );
  });

Le gestionnaire de résolution de la promesse ne fait rien, mais si la promesse est rejetée, un message d'erreur est affiché en appelant alert().

Utiliser l'option screen

Si vous souhaitez afficher l'élément en plein écran sur l'écran principal du système d'exploitation, vous pouvez utiliser un code comme celui-ci :

try {
  const ecranPrincipal = (await getScreenDetails()).screens.find(
    (screen) => screen.isPrimary,
  );
  await document.body.requestFullscreen({ screen: ecranPrincipal });
} catch (err) {
  console.error(err.name, err.message);
}

La méthode Window.getScreenDetails() est utilisée pour récupérer l'objet ScreenDetails pour l'appareil actuel, qui contient des objets ScreenDetailed représentant les différents écrans disponibles.

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'API Fullscreen
• La méthode Document.exitFullscreen()
• La propriété Document.fullscreen
• La propriété Document.fullscreenElement
• La pseudo-classe CSS :fullscreen
• L'attribut <iframe> allowfullscreen