Document: fullscreenchange — Ereignis · JavaScript-Referenz

Signatur

document.addEventListener("fullscreenchange", handler)

Beschreibung

Das Ereignis fullscreenchange tritt ein, wenn sich der Vollbildzustand ändert: Entweder hat ein Element über Element.requestFullscreen() den Vollbildmodus betreten, oder der Modus wurde verlassen. Verlassen kann ihn das Skript mit document.exitFullscreen() oder die Nutzerin bzw. der Nutzer mit Esc, F11 oder einer Browser-Geste. Das Ereignis wird zuerst am betroffenen Element ausgelöst und steigt dann (bubbles) bis zum Document auf. Deshalb reicht ein einziger Listener am document.

Das Ereignis selbst sagt nicht, in welche Richtung der Wechsel ging. Das lässt sich über document.fullscreenElement herausfinden: Ist der Wert null, wurde der Vollbildmodus verlassen. Sonst steht dort das Element, das jetzt im Vollbild angezeigt wird.

Typische Einsatzfälle sind:

die Beschriftung oder das Symbol eines Vollbild-Buttons umschalten,
Layouts oder die Größe eines Canvas anpassen,
eigene Bedienelemente eines Videoplayers ein- oder ausblenden,
Zustände aufräumen, wenn der Nutzer den Vollbildmodus selbst beendet.

Den Handler registriert man mit document.addEventListener("fullscreenchange", handler) oder über die Eigenschaft document.onfullscreenchange. Die Eigenschaft erlaubt aber nur einen einzigen Handler.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"fullscreenchange"`.
$handler Pflicht	(event: Event) => void		Callback-Funktion. Sie erhält ein normales `Event`-Objekt ohne zusätzliche Eigenschaften. `event.target` ist das Element, das den Vollbildmodus betreten oder verlassen hat.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen für `addEventListener`, z. B. `{ once: true }` oder `{ signal }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück (undefined).

Beispiele

Vollbild-Button mit Zustandsanzeige

const player = document.querySelector('#player');
const button = document.querySelector('#fs-toggle');

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);
  }
});

// Reagiert auch auf Esc oder F11, also nicht nur auf den Button
document.addEventListener('fullscreenchange', () => {
  const aktiv = document.fullscreenElement !== null;
  button.textContent = aktiv ? 'Vollbild beenden' : 'Vollbild';
  console.log(aktiv ? `Vollbild: #${document.fullscreenElement.id}` : 'Vollbild verlassen');
});

Vollbild: #player Vollbild verlassen

Handler über die on-Property und removeEventListener

const onChange = (event) => {
  console.log('Zustand geändert bei:', event.target.nodeName);
};

// Variante 1: addEventListener / removeEventListener
document.addEventListener('fullscreenchange', onChange);
// ... später, z. B. beim Abbau einer Komponente:
document.removeEventListener('fullscreenchange', onChange);

// Variante 2: on-Property (nur ein einziger Handler möglich)
document.onfullscreenchange = () => {
  console.log('Vollbild aktiv?', Boolean(document.fullscreenElement));
};
// Handler entfernen
document.onfullscreenchange = null;

Zustand geändert bei: VIDEO

Canvas-Größe anpassen und Listener per AbortController aufräumen

const canvas = document.querySelector('canvas');
const controller = new AbortController();

const resize = () => {
  const fs = document.fullscreenElement === canvas;
  canvas.width = fs ? screen.width : 640;
  canvas.height = fs ? screen.height : 360;
  console.log(`Canvas: ${canvas.width}x${canvas.height}`);
};

document.addEventListener('fullscreenchange', resize, { signal: controller.signal });

// Alle Listener auf einmal entfernen:
// controller.abort();

Canvas: 1920x1080 Canvas: 640x360

// Wichtig · Fallstricke

Richtung prüfen: Das Ereignis wird beim Betreten und beim Verlassen ausgelöst. Welcher Fall vorliegt, zeigt immer document.fullscreenElement.
Fehler beachten: Schlägt requestFullscreen() fehl, weil keine Nutzergeste vorlag, ein Iframe kein allow="fullscreen" hat oder eine Permissions Policy es verbietet, kommt kein fullscreenchange. Stattdessen wird fullscreenerror ausgelöst, und das Promise wird abgelehnt.
Präfixe: Ältere Safari-Versionen (vor 16.4) und iOS kennen nur webkitfullscreenchange und document.webkitFullscreenElement. Ältere Firefox-Versionen kannten nur mozfullscreenchange. Für breite Unterstützung beide Ereignisnamen registrieren. Auf dem iPhone unterstützt Safari die Fullscreen-API nur eingeschränkt, bei <video> über webkitEnterFullscreen().
F11-Vollbild des Browsers: Schaltet der Nutzer den Browser mit F11 in den Vollbildmodus, ist das kein API-Vollbild. Dabei wird in der Regel kein fullscreenchange ausgelöst, und fullscreenElement bleibt null.
Zeitpunkt: Das Ereignis kommt asynchron, nachdem das Promise von requestFullscreen() bzw. exitFullscreen() erfüllt wurde. Layout-Maße können sich im selben Frame noch ändern, darum für Größenberechnungen gegebenenfalls zusätzlich resize nutzen.

Siehe auch

Document: fullscreenerror Element.requestFullscreen() Document.exitFullscreen() Document.fullscreenElement Document.fullscreenEnabled Element: fullscreenchange Document: prerenderingchange