Document: fullscreenerror — Ereignis · JavaScript-Referenz

Signatur

document.addEventListener("fullscreenerror", handler)

Beschreibung

Das Ereignis fullscreenerror gehört zur Fullscreen API. Der Browser löst es aus, wenn er eine Anfrage über Element.prototype.requestFullscreen() ablehnt. Es wird zuerst am Element ausgelöst, das in den Vollbildmodus wechseln sollte. Danach steigt es im DOM nach oben (es ist bubbling und composed). Deshalb reicht ein einziger Listener auf document, um Fehler aller Elemente abzufangen.

Du registrierst den Handler entweder mit document.addEventListener("fullscreenerror", handler) oder über die Eigenschaft document.onfullscreenerror = handler. Das Ereignisobjekt ist ein gewöhnliches Event ohne zusätzliche Daten. Es lässt sich nicht abbrechen. Welches Element betroffen war, verrät event.target.

Typische Gründe für eine Ablehnung:

Der Aufruf passiert nicht direkt nach einer Nutzeraktion (keine transient activation), zum Beispiel in einem setTimeout oder nach einem await auf einen langsamen Netzwerkaufruf.
Das Element liegt in einem <iframe> ohne allow="fullscreen", oder eine Permissions Policy verbietet den Vollbildmodus.
Das Element hängt nicht im Dokument, oder der Elementtyp wird nicht unterstützt.
Der Nutzer oder eine Browser-Einstellung blockiert den Vollbildmodus.

Moderne Browser geben bei requestFullscreen() außerdem ein Promise zurück, das bei einem Fehler zurückgewiesen wird. Mit dem Ereignis kannst du Fehler zentral behandeln. Mit dem Promise behandelst du sie direkt an der Stelle, an der du den Vollbildmodus anforderst.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"fullscreenerror"`.
$handler Pflicht	(event: Event) => void		Funktion, die bei einem fehlgeschlagenen Vollbildwechsel aufgerufen wird. `event.target` ist das Element, das in den Vollbildmodus wechseln sollte.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once`, `capture` oder `signal` (zum Entfernen über einen `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück. Der Handler erhält ein Event-Objekt vom Typ fullscreenerror.

Beispiele

Fehler zentral mit addEventListener abfangen

document.addEventListener("fullscreenerror", (event) => {
  console.warn("Vollbild fehlgeschlagen für:", event.target);
  alert("Der Vollbildmodus ist hier leider nicht verfügbar.");
});

// Fehler provozieren: Aufruf ohne Nutzeraktion
document.documentElement.requestFullscreen().catch(() => {
  // Der Fehler wird zusätzlich über das Ereignis gemeldet
});

Vollbild fehlgeschlagen für: <html>

Handler über die on-Property setzen und wieder entfernen

const video = document.querySelector("video");

document.onfullscreenerror = (event) => {
  console.error(`Kein Vollbild für <${event.target.tagName.toLowerCase()}>`);
};

video.addEventListener("dblclick", () => {
  video.requestFullscreen().catch(() => {});
});

// Später, z. B. beim Verlassen der Ansicht:
// document.onfullscreenerror = null;

Kein Vollbild für <video>

Listener mit removeEventListener aufräumen

const onFullscreenError = () => {
  document.body.classList.add("no-fullscreen");
  console.log("Fallback-Layout aktiviert");
};

document.addEventListener("fullscreenerror", onFullscreenError);

const button = document.querySelector("#fullscreen-btn");
button.addEventListener("click", async () => {
  try {
    await document.querySelector("#player").requestFullscreen();
  } catch (err) {
    console.log("Promise abgelehnt:", err.name);
  }
});

// Listener entfernen, wenn die Komponente zerstört wird
const destroy = () => {
  document.removeEventListener("fullscreenerror", onFullscreenError);
};

Fallback-Layout aktiviert Promise abgelehnt: TypeError

Fehlerursache: verzögerter Aufruf verliert die Nutzeraktion

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

document.addEventListener("fullscreenerror", () => {
  console.log("Abgelehnt – Aufruf kam zu spät nach dem Klick");
}, { once: true });

button.addEventListener("click", () => {
  // Falsch: nach 6 Sekunden gilt der Klick nicht mehr als Nutzeraktion
  setTimeout(() => {
    document.documentElement.requestFullscreen().catch(() => {});
  }, 6000);
});

Abgelehnt – Aufruf kam zu spät nach dem Klick

// Wichtig · Fallstricke

Nutzeraktion erforderlich: requestFullscreen() muss kurz nach einer echten Nutzeraktion (Klick, Tastendruck) aufgerufen werden. Sonst löst der Browser fullscreenerror aus. Lange await-Ketten vor dem Aufruf können die Nutzeraktion ungültig machen.
iframes: Inhalte in einem <iframe> brauchen allow="fullscreen" (früher allowfullscreen). Sonst scheitert jede Anfrage.
Keine Fehlerdetails: Das Ereignis sagt nicht, warum die Anfrage gescheitert ist. Den Grund findest du höchstens über das zurückgewiesene Promise von requestFullscreen() oder in der Browser-Konsole.
Nicht doppelt reagieren: Ereignis und Promise-Ablehnung treten meist zusammen auf. Behandle die Nutzermeldung nur an einer Stelle, sonst erscheint sie doppelt.
Browser-Kompatibilität: Ältere Safari-Versionen (vor 16.4) kennen nur webkitfullscreenerror bzw. onwebkitfullscreenerror. Auf dem iPhone unterstützt iOS keine Element-Vollbildansicht, dort gibt es nur video.webkitEnterFullscreen(). Ob die API grundsätzlich verfügbar ist, prüfst du vorher mit document.fullscreenEnabled.

Siehe auch

Document: fullscreenchange Element.prototype.requestFullscreen() Document.prototype.exitFullscreen() Document.fullscreenElement Document.fullscreenEnabled Element: fullscreenerror DocumentPictureInPicture: enter