HOWTO · JavaScript

Wie man Fullscreen in JavaScript verwendet

Erfahren Sie, wie Sie mit JavaScript den Vollbildmodus für ein Element anfordern, ihn beenden und auf Änderungen des Vollbildstatus reagieren.

Auf dieser Seite

Mit der Vollbild-API des Browsers können Sie für ein ausgewähltes Element den Vollbildmodus anfordern, ihn mit document.exitFullscreen() beenden und die Oberfläche über fullscreenchange mit dem aktuellen Zustand synchronisieren. Rufen Sie die Anforderung als Reaktion auf eine Benutzeraktion auf, etwa einen Klick auf eine Schaltfläche, und behandeln Sie das zurückgegebene Promise: Der Browser kann die Anforderung ablehnen.

Die Fullscreen-API verstehen

Der Vollbildmodus gilt für ein Element, zum Beispiel einen Videoplayer, ein Spiel, eine Präsentation oder einen Seitenbereich. Das aktive Element ist über document.fullscreenElement verfügbar; wenn sich kein Element im Vollbildmodus befindet, ist der Wert null. Die Vollbild-API wird vom Browser gesteuert. Je nach Benutzeraktion, Browsing-Kontext und Gerät kann eine Anforderung daher nicht verfügbar sein oder abgelehnt werden.

Details zu Methoden und Ereignissen finden Sie in der MDN-Dokumentation zur Fullscreen-API.

Methode 1: Mit requestFullscreen() den Vollbildmodus aktivieren

Wählen Sie das Element aus, das vergrößert werden soll, und rufen Sie requestFullscreen() als Reaktion auf einen Klick auf. Die Vollbild-API setzt einen sicheren Kontext voraus, in der Regel HTTPS. Die Methode ist möglicherweise nicht verfügbar, wenn die Seite nicht in einem sicheren Kontext ausgeführt wird oder die Methode fehlt. Eine Anforderung kann außerdem abgelehnt werden, wenn sie nicht durch eine Benutzeraktion ausgelöst wird oder der Browsing-Kontext beziehungsweise das Gerät sie nicht zulässt. Das folgende Seitenfragment ist ein statisches Browserbeispiel; sein API-Verhalten hängt vom Browser ab und wird hier nicht als Laufzeitausgabe dargestellt.

<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>

Das obige Browserbeispiel verwendet ein echtes DOM-Element. Das folgende separate Beispiel nutzt einen Platzhalter, um den Ablauf des Promise und die nach Abschluss der Anforderung angezeigte Meldung zu veranschaulichen. Die unveränderte Beispielausgabe kann englische Beschriftungen enthalten. Führen Sie dieses Beispiel aus:

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

Rufen Sie die Anforderung in Ihrer Seite innerhalb des Klick-Handlers auf, damit sie durch eine Benutzeraktion ausgelöst wird. Verlassen Sie sich nicht auf herstellerspezifische Präfixe als Garantie für die Unterstützung. Prüfen Sie, ob die standardisierte Methode vorhanden ist, und sorgen Sie dafür, dass die übrige Oberfläche nutzbar bleibt, falls sie fehlt oder das Promise abgelehnt wird. Wenn die API scheinbar nicht verfügbar ist, prüfen Sie auch, ob die Seite in einem sicheren Kontext ausgeführt wird, üblicherweise über HTTPS.

Methode 2: Den Vollbildmodus mit exitFullscreen() beenden

Rufen Sie document.exitFullscreen() auf, um den Vollbildmodus zu beenden. Die Methode gibt ein Promise zurück; behandeln Sie eine Ablehnung genauso wie beim Aktivieren des Vollbildmodus. Nutzer können den Modus auch über Browser- oder Gerätesteuerungen verlassen. Ihre Oberfläche sollte diese Änderung berücksichtigen und nicht davon ausgehen, dass nur die eigene Beenden-Schaltfläche den Vollbildmodus beenden kann.

Auf einer Browserseite können Sie beispielsweise einen Klick-Handler an eine Beenden-Schaltfläche binden und document.exitFullscreen() aufrufen, wenn document.fullscreenElement gesetzt ist. Fangen Sie eine Ablehnung des Promises ab und zeigen Sie eine hilfreiche Statusmeldung an. Die konkrete Interaktion mit dem Browser wird durch diese statische Beschreibung nicht ausgeführt.

Methode 3: Änderungen des Vollbildstatus behandeln

Hören Sie auf fullscreenchange am document. Das Ereignis wird bei Änderungen des Vollbildstatus ausgelöst, auch wenn Nutzer den Modus über die Browsersteuerung beenden. Lesen Sie jedes Mal document.fullscreenElement: Ein Wert ungleich null bezeichnet das aktuelle Vollbildelement; bei null ist der Vollbildmodus beendet. Aktualisieren Sie anhand dieses Zustands Schaltflächenbeschriftungen, Statustexte oder andere Steuerelemente. Mit der CSS-Pseudoklasse :fullscreen können Sie ein Element gestalten, während der Browser es im Vollbildmodus anzeigt.

Fazit

Rufen Sie requestFullscreen() für das ausgewählte Element als Reaktion auf eine Benutzeraktion auf und behandeln Sie das Promise. Bieten Sie eine Möglichkeit zum Beenden an, die document.exitFullscreen() verwendet. Verfolgen Sie fullscreenchange und document.fullscreenElement, damit die Oberfläche auch auf außerhalb der Seite ausgelöste Beendigungen reagiert. Das Verhalten kann je nach Browser und Gerät variieren; stellen Sie deshalb sicher, dass die Seite auch ohne Vollbildmodus nutzbar bleibt.

FAQ

  1. Wie prüfe ich, ob sich ein Element im Vollbildmodus befindet? Prüfen Sie, ob document.fullscreenElement genau dieses Element enthält. Wenn kein Element aktiv ist, lautet der Wert null.

  2. Kann jedes Element in den Vollbildmodus wechseln? Die API nimmt ein Element entgegen, doch Browserrichtlinien und der umgebende Browsing-Kontext können beeinflussen, ob die Anforderung erfolgreich ist. Lösen Sie sie durch eine Benutzeraktion aus und behandeln Sie mögliche Fehler.

  3. Warum kann requestFullscreen() fehlschlagen? Die Methode ist möglicherweise nicht verfügbar, etwa wenn die Seite nicht in einem sicheren Kontext ausgeführt wird, üblicherweise HTTPS. Eine Anforderung kann auch ohne Benutzeraktion erfolgen oder für den aktuellen Browsing-Kontext beziehungsweise das Gerät abgelehnt werden. Prüfen Sie die Verfügbarkeit und behandeln Sie das zurückgegebene Promise.

  4. Wie kann ich Inhalte im Vollbildmodus gestalten? Verwenden Sie die CSS-Pseudoklasse :fullscreen, um Stile anzuwenden, solange sich ein Element im Vollbildmodus befindet.