Element: fullscreenchange — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("fullscreenchange", handler)

Beschreibung

Das Ereignis fullscreenchange wird ausgelöst, sobald ein Element über die Fullscreen-API in den Vollbildmodus gewechselt ist oder ihn wieder verlassen hat. Das gilt für beide Wege: element.requestFullscreen() bzw. document.exitFullscreen() genauso wie für das Beenden durch den Nutzer, etwa mit der Esc-Taste oder über die Bedienelemente des Browsers.

Das Ereignis wird am betroffenen Element ausgelöst und steigt dann bis zum document auf (Bubbling). Man kann also entweder direkt am Element lauschen (element.addEventListener("fullscreenchange", …) bzw. element.onfullscreenchange) oder zentral am document. Letzteres ist praktisch, wenn mehrere Elemente in den Vollbildmodus wechseln können.

Das Ereignisobjekt selbst sagt nicht, ob der Vollbildmodus gerade beginnt oder endet. Das erfährst du über document.fullscreenElement: Ist es null, ist kein Element mehr im Vollbild. Sonst verweist es auf das Element, das gerade im Vollbild angezeigt wird. Typische Anwendungen sind das Umschalten von Bedienelementen (z. B. Symbol „Vollbild beenden“), das Anpassen des Layouts oder das Mitverfolgen von Nutzungsdaten bei Video-Playern.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"fullscreenchange"`.
$handler Pflicht	(event: Event) => void		Callback, der ein normales `Event` erhält. `event.target` ist das Element, das in den Vollbildmodus gewechselt ist oder ihn verlassen hat.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once`, `capture`, `passive` oder `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Den Zustand liest du im Handler über document.fullscreenElement aus.

Beispiele

Vollbild-Umschalter für einen Video-Player

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

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

Vollbild aktiv Vollbild beendet

Zentral am document lauschen

document.addEventListener('fullscreenchange', (event) => {
  const el = document.fullscreenElement;
  if (el) {
    console.log(`Vollbild: #${el.id}`);
    document.body.classList.add('is-fullscreen');
  } else {
    console.log(`Vollbild verlassen von #${event.target.id}`);
    document.body.classList.remove('is-fullscreen');
  }
});

Vollbild: #galerie Vollbild verlassen von #galerie

on-Property verwenden und Listener wieder entfernen

const karte = document.querySelector('#karte');

// Variante 1: on-Property (ersetzt vorherige Handler)
karte.onfullscreenchange = () => {
  console.log('Status geändert:', Boolean(document.fullscreenElement));
};

// Variante 2: benannter Listener, der sich entfernen lässt
const onChange = () => {
  // Karte neu zeichnen, da sich die Größe geändert hat
  console.log('Neue Größe:', karte.clientWidth, 'x', karte.clientHeight);
};
karte.addEventListener('fullscreenchange', onChange);

// Später, z. B. beim Abbau der Komponente:
karte.removeEventListener('fullscreenchange', onChange);
karte.onfullscreenchange = null;

Status geändert: true Neue Größe: 1920 x 1080

// Wichtig · Fallstricke

Keine Richtungsangabe: Das Ereignis wird beim Betreten und beim Verlassen des Vollbilds ausgelöst. Prüfe immer document.fullscreenElement.
Fehler: Scheitert requestFullscreen() (z. B. ohne Nutzeraktion oder weil ein <iframe> kein allow="fullscreen" hat), wird stattdessen fullscreenerror ausgelöst und das Promise abgelehnt.
Verlassen per Esc: Beendet der Nutzer das Vollbild mit Esc, wird ebenfalls fullscreenchange ausgelöst. Nur so kann die Oberfläche zuverlässig synchron bleiben. Das Drücken von Esc selbst lässt sich nicht abfangen.
Hat das verlassende Element den Dokumentbaum verlassen (z. B. wurde es entfernt), wird das Ereignis am document ausgelöst. Ein Listener am document ist deshalb robuster.
Kompatibilität: Ältere Safari-Versionen (vor 16.4, iOS teilweise) unterstützen nur webkitfullscreenchange und webkitFullscreenElement. Auf dem iPhone ist die Fullscreen-API für beliebige Elemente weiterhin eingeschränkt. Ältere Firefox-Versionen nutzten mozfullscreenchange.
Das Vollbild über F11 im Browser ist nicht das Vollbild der Fullscreen-API und löst dieses Ereignis nicht aus.

Siehe auch

Element.requestFullscreen() Document.exitFullscreen() Document.fullscreenElement Element: fullscreenerror Document: fullscreenchange EventTarget.addEventListener() Element: cut