Document.fullscreenEnabled — Eigenschaft · JavaScript-Referenz

Signatur

get Document.fullscreenEnabled

Beschreibung

Die Eigenschaft document.fullscreenEnabled gibt einen booleschen Wert zurück. Er zeigt an, ob die Fullscreen API im aktuellen Kontext genutzt werden darf, ob also ein späterer Aufruf von Element.requestFullscreen() überhaupt Erfolg haben kann.

Der Wert ist false, wenn der Browser den Vollbildmodus nicht unterstützt oder das Dokument ihn nicht nutzen darf. Das passiert typischerweise in einem <iframe> ohne das Attribut allowfullscreen (bzw. allow="fullscreen") oder wenn eine Permissions Policy die Funktion fullscreen sperrt.

Prüfe die Eigenschaft am besten, bevor du Bedienelemente wie einen „Vollbild“-Knopf anzeigst. So bekommen Nutzer keine Funktion zu sehen, die nicht funktioniert. Die Eigenschaft sagt nur, ob Vollbild erlaubt ist, nicht ob gerade ein Element im Vollbild angezeigt wird. Dafür gibt es document.fullscreenElement.

Beispiele

Vollbild-Knopf nur bei Unterstützung anzeigen

const button = document.querySelector('#fullscreen-btn');
const video = document.querySelector('video');

if (document.fullscreenEnabled) {
  button.hidden = false;
  button.addEventListener('click', async () => {
    try {
      await video.requestFullscreen();
    } catch (err) {
      console.error('Vollbild fehlgeschlagen:', err.message);
    }
  });
} else {
  button.hidden = true;
  console.log('Vollbild ist hier nicht verfügbar.');
}

Vollbild umschalten mit Prüfung

const toggleFullscreen = async (el = document.documentElement) => {
  if (!document.fullscreenEnabled) {
    console.warn('Vollbildmodus nicht erlaubt');
    return;
  }
  if (document.fullscreenElement) {
    await document.exitFullscreen();
  } else {
    await el.requestFullscreen();
  }
};

document.addEventListener('keydown', (e) => {
  if (e.key === 'f') toggleFullscreen();
});

Verhalten in einem iframe

// Im Elterndokument:
// <iframe src="player.html"></iframe>                   -> false
// <iframe src="player.html" allow="fullscreen"></iframe> -> true

// In player.html:
console.log('Vollbild erlaubt:', document.fullscreenEnabled);

Vollbild erlaubt: false

// Wichtig · Fallstricke

Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert und wirft im Strict Mode keinen Fehler, weil es nur einen Getter gibt.
Auch wenn der Wert true ist, kann requestFullscreen() fehlschlagen. Die Methode verlangt eine Nutzeraktion (transient activation), etwa einen Klick. Behandle deshalb immer das zurückgegebene Promise.
Ältere Browser kennen nur Präfix-Varianten wie webkitFullscreenEnabled (Safari) oder mozFullScreenEnabled (altes Firefox). Für diese Browser brauchst du eine Abfrage mit Rückfall, z. B. document.fullscreenEnabled ?? document.webkitFullscreenEnabled.
Safari auf dem iPhone unterstützt die Fullscreen API für beliebige Elemente erst seit iOS 16.4 bzw. 17 und auch dann nur eingeschränkt. Für <video> gibt es dort webkitEnterFullscreen().
In iframes steuern das Attribut allow="fullscreen" und die HTTP-Header Permissions-Policy den Wert.

Siehe auch

Element.requestFullscreen() Document.exitFullscreen() Document.fullscreenElement Document.firstElementChild TextEncoderStream.readable