Document.exitFullscreen() — Methode · JavaScript-Referenz

Signatur

Document.prototype.exitFullscreen()

Beschreibung

document.exitFullscreen() ist das Gegenstück zu Element.requestFullscreen(). Die Methode verlangt vom Browser, das Element, das gerade im Vollbildmodus angezeigt wird (erreichbar über document.fullscreenElement), wieder in die normale Darstellung zurückzuführen. Danach hat das Fenster wieder seine ursprüngliche Größe.

Die Methode gibt ein Promise zurück. Es wird erfüllt, sobald der Vollbildmodus vollständig beendet ist. Schlägt der Vorgang fehl, etwa weil gar kein Element im Vollbild ist, wird es mit einem TypeError abgelehnt. Außerdem wird am Dokument das Event fullscreenchange ausgelöst. Darauf kann man reagieren, um die Oberfläche anzupassen, zum Beispiel ein Symbol umzuschalten.

Wurde der Vollbildmodus verschachtelt angefordert (ein Element im Vollbild fordert für ein Kindelement erneut Vollbild an), stellt ein Aufruf von exitFullscreen() nur das vorherige Vollbild-Element wieder her. Der Modus wird also nicht unbedingt ganz verlassen. Nutzer können das Vollbild außerdem jederzeit selbst mit Esc oder F11 beenden. Deshalb sollte der Zustand der Oberfläche immer über fullscreenchange abgeglichen werden und nicht nur beim eigenen Aufruf.

Anders als requestFullscreen() braucht exitFullscreen() keine Nutzeraktion (transiente Aktivierung). Die Methode darf also auch aus Timern oder asynchronem Code heraus aufgerufen werden.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald der Vollbildmodus beendet ist. Es wird mit einem TypeError abgelehnt, wenn das Dokument nicht aktiv ist oder kein Element im Vollbild dargestellt wird.

Beispiele

Vollbild sicher beenden

const verlasseVollbild = async () => {
  // Nur aufrufen, wenn wirklich ein Element im Vollbild ist
  if (!document.fullscreenElement) {
    console.log('Kein Vollbild aktiv');
    return;
  }
  try {
    await document.exitFullscreen();
    console.log('Vollbild beendet');
  } catch (err) {
    console.error('Beenden fehlgeschlagen:', err.message);
  }
};

document.querySelector('#exit-btn').addEventListener('click', verlasseVollbild);

Vollbild beendet

Vollbild-Umschalter für einen Videoplayer

const player = document.querySelector('#player');
const toggleBtn = document.querySelector('#fullscreen-toggle');

toggleBtn.addEventListener('click', async () => {
  try {
    if (document.fullscreenElement) {
      await document.exitFullscreen();
    } else {
      await player.requestFullscreen();
    }
  } catch (err) {
    console.error(`Fehler: ${err.name} – ${err.message}`);
  }
});

// Oberfläche synchron halten, auch wenn der Nutzer Esc drückt
document.addEventListener('fullscreenchange', () => {
  const aktiv = document.fullscreenElement !== null;
  toggleBtn.textContent = aktiv ? 'Vollbild verlassen' : 'Vollbild';
  console.log('Vollbild aktiv:', aktiv);
});

Vollbild aktiv: true Vollbild aktiv: false

Vollbild nach Ende einer Präsentation automatisch verlassen

const praesentation = document.querySelector('#slides');
const video = praesentation.querySelector('video');

// Kein Nutzerklick nötig: exitFullscreen() geht auch aus Event-Handlern und Timern
video.addEventListener('ended', () => {
  if (document.fullscreenElement === praesentation) {
    setTimeout(() => {
      document.exitFullscreen()
        .then(() => console.log('Präsentation beendet, Vollbild verlassen'));
    }, 2000);
  }
});

Präsentation beendet, Vollbild verlassen

Fallback für ältere Browser mit Präfix

const exitFullscreenCompat = () => {
  if (document.exitFullscreen) {
    return document.exitFullscreen();
  }
  if (document.webkitExitFullscreen) {
    // Ältere Safari-Versionen: kein Promise
    document.webkitExitFullscreen();
    return Promise.resolve();
  }
  return Promise.reject(new Error('Fullscreen-API nicht unterstützt'));
};

const istVollbild = () =>
  Boolean(document.fullscreenElement ?? document.webkitFullscreenElement);

if (istVollbild()) {
  exitFullscreenCompat().then(() => console.log('Beendet'));
}

Beendet

// Wichtig · Fallstricke

Ablehnung ohne Vollbild: Wird die Methode aufgerufen, obwohl kein Element im Vollbild ist, lehnt das Promise mit einem TypeError ab. In Chrome erscheint dann „Document not active“ bzw. „Not in fullscreen“. Deshalb vorher document.fullscreenElement prüfen oder den Aufruf mit catch absichern.
Verschachteltes Vollbild: Ein Aufruf verlässt nur die oberste Ebene des Vollbild-Stapels. Zum vollständigen Beenden gegebenenfalls in einer Schleife aufrufen, bis document.fullscreenElement den Wert null hat.
Aufruf am Dokument, nicht am Element: Es gibt kein element.exitFullscreen(). Die Methode existiert nur an Document. In iframes betrifft sie das Dokument des iframes. Damit Vollbild dort überhaupt möglich ist, braucht der iframe allow="fullscreen".
Browser-Kompatibilität: In allen aktuellen Browsern ist die Methode ohne Präfix und mit Promise verfügbar. Ältere Safari-Versionen kennen nur webkitExitFullscreen() ohne Promise, alte Firefox-Versionen nur mozCancelFullScreen(). Auf dem iPhone unterstützt Safari erst ab iOS 16.4 Vollbild für Elemente, die kein Video sind. Davor gab es für Videos nur HTMLVideoElement.webkitExitFullscreen().
Nutzer hat Vorrang: Nutzer können das Vollbild jederzeit mit Esc beenden, ohne dass die Seite das verhindern kann. Oberflächenzustände deshalb immer über das Event fullscreenchange aktualisieren.

Siehe auch

Element.requestFullscreen() Document.fullscreenElement Document.fullscreenEnabled Document new URL()