Document.fullscreen — Eigenschaft · JavaScript-Referenz

Signatur

Document.fullscreen

Beschreibung

document.fullscreen liefert true, wenn im Dokument gerade ein Element im Vollbildmodus angezeigt wird, sonst false. Die Eigenschaft gehört zur Fullscreen API und ist schreibgeschützt. Zuweisungen werden ignoriert und lösen im Strict Mode einen TypeError aus.

Die Eigenschaft gilt als veraltet. Die Spezifikation empfiehlt stattdessen document.fullscreenElement. Diese Eigenschaft liefert das Element, das gerade im Vollbild ist, oder null. Das entspricht document.fullscreenElement !== null und verrät zusätzlich, welches Element im Vollbild ist.

Typische Anwendungsfälle sind Umschaltknöpfe für Video-Player, Präsentationen, Spiele oder Bildbetrachter. Dort muss man den aktuellen Zustand kennen, um zwischen element.requestFullscreen() und document.exitFullscreen() zu wählen. Zustandsänderungen erkennt man am Ereignis fullscreenchange.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn gerade ein Element des Dokuments im Vollbildmodus angezeigt wird, sonst false.

Beispiele

Vollbild-Zustand abfragen

// Veraltete Variante
console.log(document.fullscreen);

// Empfohlene, gleichwertige Variante
const isFullscreen = document.fullscreenElement !== null;
console.log(isFullscreen);

false false

Vollbild für einen Video-Player umschalten

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

button.addEventListener('click', async () => {
  try {
    if (document.fullscreenElement) {
      await document.exitFullscreen();
    } else {
      await player.requestFullscreen();
    }
  } catch (err) {
    console.error('Vollbild nicht möglich:', err.message);
  }
});

Auf Zustandswechsel reagieren

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

document.addEventListener('fullscreenchange', () => {
  const active = document.fullscreenElement !== null;
  button.textContent = active ? 'Vollbild beenden' : 'Vollbild';
  console.log('Vollbild aktiv:', active);
});

Vollbild aktiv: true

Robuste Hilfsfunktion mit Fallback

const isInFullscreen = () =>
  Boolean(
    document.fullscreenElement ??
    document.webkitFullscreenElement ??
    document.fullscreen ??
    false
  );

console.log(isInFullscreen());

false

// Wichtig · Fallstricke

Veraltet: Verwende in neuem Code document.fullscreenElement. Die Browser unterstützen document.fullscreen zwar weiterhin, ihre Zukunft ist aber ungewiss.
Präfixe: Ältere Safari-Versionen (vor 16.4, auf dem iPhone besonders lange) kennen nur document.webkitIsFullScreen bzw. webkitFullscreenElement. Alte Firefox-Versionen (vor 64) kennen nur mozFullScreen. Auf dem iPhone unterstützt Safari die Fullscreen API für beliebige Elemente nur eingeschränkt, für Videos gibt es video.webkitEnterFullscreen().
Vollbild per F11 ist kein API-Vollbild: Schaltet der Nutzer das Browser-Vollbild mit F11 ein, bleibt document.fullscreen in der Regel false, und es wird kein fullscreenchange ausgelöst.
iframes: Der Wert bezieht sich auf das jeweilige Dokument. Vollbild in einem iframe erfordert das Attribut allow="fullscreen" (früher allowfullscreen).
Schreibschutz: Mit einer Zuweisung wie document.fullscreen = true startet kein Vollbild. Dafür ist element.requestFullscreen() nötig, und der Aufruf muss aus einer Nutzeraktion wie einem Klick oder Tastendruck kommen.

Siehe auch

Document.fullscreenElement Document.fullscreenEnabled Element.prototype.requestFullscreen() Document.prototype.exitFullscreen() PaymentAddress.region