Utiliser le mode plein écran

L'API plein écran fournit un moyen simple de présenter du contenu web en utilisant l'ensemble de l'écran de l'utilisateur. Cet article fournit des informations sur l'utilisation de l'API.

L'API permet de demander facilement au navigateur de faire en sorte qu'un élément et ses enfants occupent tout l'écran, éliminant ainsi toute l'interface utilisateur du navigateur et les autres applications de l'écran pendant ce temps.

Activer le mode plein écran

En partant d'un élément que vous aimeriez afficher en plein écran (<video>, par exemple), vous pouvez le passer en plein écran simplement en appelant sa méthode requestFullscreen() ; cette méthode est implémentée dans Gecko en tant que element.mozRequestFullScreen() et dans WebKit en tant que element.webkitRequestFullscreen().

Prenons cet élément <video> :

<video controls id="myvideo">
  <source src="somevideo.webm"></source>
  <source src="somevideo.mp4"></source>
</video>

Nous pouvons mettre cet élément video en plein écran avec un script de cette façon :

var elem = document.getElementById("myvideo");
if (elem.requestFullscreen) {
  elem.requestFullscreen();
} else if (elem.mozRequestFullScreen) {
  elem.mozRequestFullScreen();
} else if (elem.webkitRequestFullscreen) {
  elem.webkitRequestFullscreen();
}

Différences de présentation

Il est important de savoir qu'il y a une différence clef entre les implémentations de Gecko et WebKit : Gecko ajoute automatiquement des règles CSS à l'élément afin qu'il remplisse l'écran : "width: 100%; height: 100%". WebKit ne fait pas ça ; à la place, il centre l'élément sans le redimensionner au milieu d'un écran noir. Pour obtenir le même comportement que Gecko dans WebKit, vous devez ajouter votre propre règle "width: 100%; height: 100%;" à l'élément :

#myvideo:-webkit-full-screen  {
  width: 100%;
  height: 100%;
}

D'un autre côté, si vous essayez d'émuler le comportement de WebKit sur Gecko, vous devez placer l'élément que vous souhaitez présenter dans un autre élément, que vous mettrez en plein écran, et utiliser des règles CSS pour ajuster l'apparence de l'élément interne.

Notification

Quand le mode plein écran est activé, le document qui contient l'élément reçoit un événement de type  mozfullscreenchange. Lors de la sortie du mode plein écran, le document reçoit à nouveau l'événement  mozfullscreenchange. Notez que l'événement  en lui-même mozfullscreenchange ne fournit aucune information si le document est en train d'entrer ou de sortir du mode plein écran, mais si le document a une valeur non nulle mozFullScreenElement, vous savez que vous êtes en mode plein écran.

Lorsqu'une demande de plein écran échoue

Il n'est pas garanti que vous soyez capable de passer en mode plein écran. Par exemple, les élements <iframe> possèdent l'attribut mozallowfullscreen  (webkitallowfullscreen, etc) pour permettre à leur contenu d'être affiché en mode plein écran. Certains contenus comme les greffons fenêtrés ne peuvent être représentés en plein écran. Essayer de placer un élément qui ne peut être affiché en mode plein écran (ou le parent ou le descendant d'un tel élément) ne marchera pas. A la place, l'élément qui a demandé le mode plein écran recevra un événement  mozfullscreenerror . Quand une demande de plein écran échoue, Firefox écrit un message d'erreur dans la console Web expliquant pourquoi la demande n'a pas pu aboutir..

Sortir du mode plein écran

L'utilisateur peut toujours du mode plein écran quand il le désire; voir Things your users want to know. Vous pouvez également le faire en appelant la méthode cancelFullscreen() ; Elle est implémentée dans  Gecko sous le nom  mozCancelFullScreen() et dans  WebKit comme webkitCancelFullScreen().

Other information

The document provides some additional information that can be useful when developing fullscreen web applications:

fullscreenElement

The fullscreenElement attribute tells you the element that's currently being displayed fullscreen. If this is non-null, the document is in fullscreen mode. If this is null, the document is not in fullscreen mode.

fullscreenEnabled

The fullscreenEnabled attribute tells you whether or not the document is currently in a state that would allow fullscreen mode to be requested.

Things your users want to know

You'll want to be sure to let your users know that they can press the ESC key (or F11) to exit fullscreen mode.

In addition, navigating to another page, changing tabs, or switching to another application (using, for example, Alt-Tab) while in fullscreen mode exits fullscreen mode as well.

Example

In this example, a video is presented in a web page. Pressing the Return or Enter key lets the user toggle between windowed and fullscreen presentation of the video.

Voir l'exemple sur une page

Watching for the Enter key

When the page is loaded, this code is run to set up an event listener to watch for the 'enter' key.

document.addEventListener("keydown", function(e) {
  if (e.keyCode == 13) {
    toggleFullScreen();
  }
}, false);

Toggling fullscreen mode

This code is called when the user hits the Enter key, as seen above.

function toggleFullScreen() {
  if (!document.fullscreenElement &&    // alternative standard method
      !document.mozFullScreenElement && !document.webkitFullscreenElement) {  // current working methods
    if (document.documentElement.requestFullscreen) {
      document.documentElement.requestFullscreen();
    } else if (document.documentElement.mozRequestFullScreen) {
      document.documentElement.mozRequestFullScreen();
    } else if (document.documentElement.webkitRequestFullscreen) {
      document.documentElement.webkitRequestFullscreen(Element.ALLOW_KEYBOARD_INPUT);
    }
  } else {
    if (document.cancelFullScreen) {
      document.cancelFullScreen();
    } else if (document.mozCancelFullScreen) {
      document.mozCancelFullScreen();
    } else if (document.webkitCancelFullScreen) {
      document.webkitCancelFullScreen();
    }
  }
}

This starts by looking at the value of the fullscreenElement attribute on the document (checking it prefixed with both -moz- and -webkit-). If it's null, the document is currently in windowed mode, so we need to switch to fullscreen mode. Switching to fullscreen mode is done by calling either element.mozRequestFullScreen() or webkitRequestFullscreen(), depending on which is available.

If fullscreen mode is already active (fullscreenElement is non-null), we call document.mozCancelFullScreen() or webkitCancelFullScreen(), again depending on which browser is in use.

Browser compatibility

Although both Gecko and WebKit implement a draft of this API, there are some subtle differences. This document doesn't necessarily try to call them all into focus. The article will be revised as the spec and implementations fall closer into alignment with one another.

Gecko notes

Although this API was introduced in Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6), it's not enabled by default in that release. To enable it, set the full-screen-api.enabled preference to true. The API is enabled by default in Gecko 10.0 (Firefox 10.0 / Thunderbird 10.0 / SeaMonkey 2.7). In Gecko all the API is spelt "fullScreen".

Specification

Fullscreen API

Non-standard methods

These are some of the methods that browsers implemented before the standard was drafted. Having the standard methods described above it's better to avoid using the following ones:

• window.fullScreen (Firefox)
• HTMLMediaElement.webkitDisplayingFullscreen
• HTMLMediaElement.webkitEnterFullscreen
• HTMLMediaElement.webkitExitFullscreen
• HTMLMediaElement.webkitSupportsFullscreen

See also

• element.mozRequestFullScreen()
• element.mozCancelFullScreen()
• document.mozFullScreen
• document.mozFullScreenElement
• document.mozFullScreenEnabled
• :-moz-full-screen
• :-moz-full-screen-ancestor
• allowfullscreen

• Blog post: Firefox's HTML full-screen API enabled in Nightly builds