Element: fullscreenerror — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("fullscreenerror", handler)

Beschreibung

Das Ereignis fullscreenerror wird an dem Element ausgelöst, für das Element.requestFullscreen() aufgerufen wurde, wenn der Browser den Wechsel in den Vollbildmodus ablehnt. Es steigt im DOM auf (Bubbling) und kann deshalb auch zentral am document abgefangen werden. Der Handler bekommt ein einfaches Event ohne Fehlerdetails.

Typische Gründe für eine Ablehnung:

Der Aufruf kam nicht aus einer Benutzeraktion wie einem Klick oder Tastendruck (fehlende transient activation).
Das Element steckt in einem <iframe> ohne das Attribut allow="fullscreen", oder eine Permissions-Policy verbietet den Vollbildmodus.
Das Element ist nicht mit dem Dokument verbunden, oder es ist ein nicht unterstütztes Element (z. B. ein <dialog>, das modal geöffnet ist).
Der Benutzer oder die Browser-Einstellungen blockieren den Vollbildmodus.

Du kannst das Ereignis mit addEventListener("fullscreenerror", …) oder über die Eigenschaft onfullscreenerror behandeln. requestFullscreen() gibt außerdem ein Promise zurück, das im Fehlerfall mit einem TypeError abgelehnt wird. In modernem Code fängst du Fehler meist direkt über das Promise ab. Das Ereignis lohnt sich vor allem für zentrales Logging oder für die Anzeige eines Hinweises in der Oberfläche.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"fullscreenerror"`.
$handler Pflicht	(event: Event) => void		Callback, der ein normales `Event` erhält. `event.target` ist das Element, dessen Vollbild-Anfrage gescheitert ist.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `capture`, `passive` oder `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück.

Beispiele

Fehler beim Vollbild-Wechsel mit addEventListener abfangen

const video = document.querySelector('#player');

video.addEventListener('fullscreenerror', (event) => {
  console.warn('Vollbild nicht möglich für:', event.target.id);
});

// Absichtlich ohne Benutzeraktion aufgerufen, darum schlägt der Aufruf fehl
video.requestFullscreen().catch((err) => {
  console.error(err.name, err.message);
});

Vollbild nicht möglich für: player TypeError Permissions check failed

on-Property und Hinweis in der Oberfläche

const btn = document.querySelector('#fs-btn');
const box = document.querySelector('#galerie');
const hint = document.querySelector('#hinweis');

box.onfullscreenerror = () => {
  hint.textContent = 'Vollbild wird von deinem Browser oder dieser Einbettung blockiert.';
  hint.hidden = false;
};

btn.addEventListener('click', () => {
  // Per Klick ausgelöst, gilt also als Benutzeraktion
  box.requestFullscreen().catch(() => {});
});

Zentral am document protokollieren und Listener wieder entfernen

const onFsError = (event) => {
  console.log('fullscreenerror bei', event.target.tagName);
};

document.addEventListener('fullscreenerror', onFsError);

// Später, z. B. beim Abbau einer Komponente:
document.removeEventListener('fullscreenerror', onFsError);

fullscreenerror bei VIDEO

Promise-basierte Variante mit async/await

const enterFullscreen = async (el) => {
  if (!document.fullscreenEnabled) {
    console.log('Vollbild ist hier nicht verfügbar');
    return false;
  }
  try {
    await el.requestFullscreen({ navigationUI: 'hide' });
    return true;
  } catch (err) {
    console.log('Abgelehnt:', err.message);
    return false;
  }
};

document.querySelector('#start').addEventListener('click', () => {
  enterFullscreen(document.documentElement);
});

// Wichtig · Fallstricke

Das Ereignis enthält keine Fehlerdetails. Den Grund für die Ablehnung erfährst du nur über die Ablehnung des Promise von requestFullscreen(), und auch dort ist die Meldung je nach Browser unterschiedlich.
Benutzeraktion nötig: requestFullscreen() muss direkt aus einem Klick- oder Tastatur-Handler heraus aufgerufen werden. Ein Aufruf nach einem await auf eine langsame Netzwerkanfrage kann schon außerhalb dieses Zeitfensters liegen und scheitert dann.
iframes: Eingebettete Inhalte brauchen <iframe allow="fullscreen"> (das ältere allowfullscreen geht auch). Prüfe vorher mit document.fullscreenEnabled, ob Vollbild überhaupt möglich ist.
Kompatibilität: Ältere Safari-Versionen (vor 16.4) kennen nur webkitfullscreenerror und webkitRequestFullscreen(). Alte Firefox-Versionen nutzten mozfullscreenerror. Auf dem iPhone unterstützt Safari die Fullscreen-API für beliebige Elemente nicht, nur für <video> über webkitEnterFullscreen().
Das Ereignis wird zusätzlich zur Promise-Ablehnung ausgelöst. Wenn du beides behandelst, zeige einen Fehlerhinweis nicht doppelt an.

Siehe auch

Element: fullscreenchange Element.requestFullscreen() Document.exitFullscreen() Document.fullscreenElement Document.fullscreenEnabled EventTarget.addEventListener() Element: copy