Element.requestFullscreen() — Methode · JavaScript-Referenz

Signatur

Element.prototype.requestFullscreen(options)

Beschreibung

requestFullscreen() fordert den Browser auf, ein bestimmtes Element (z. B. ein <video>, ein <canvas> oder einen Container mit einer Präsentation) auf dem gesamten Bildschirm anzuzeigen. Die Methode gibt ein Promise zurück. Es wird erfüllt, sobald der Vollbildmodus aktiv ist, und abgelehnt, wenn der Browser die Anfrage verweigert.

Aus Sicherheitsgründen klappt der Aufruf nur mit einer vorübergehenden Nutzeraktivierung (transient user activation). Er muss also direkt in einem Handler für eine Nutzerinteraktion wie click oder keydown stehen. Außerdem muss das Element im Dokument hängen und darf kein <dialog> sein. Liegt es in einem <iframe>, braucht dieser das Attribut allow="fullscreen".

Ist der Vollbildmodus aktiv, verweist document.fullscreenElement auf das Element. Mit der CSS-Pseudoklasse :fullscreen und dem Pseudoelement ::backdrop lässt sich die Darstellung anpassen. Beenden kann man den Modus mit document.exitFullscreen(), oder der Nutzer drückt Esc. Jeder Wechsel löst am Element und am Dokument das Event fullscreenchange aus. Schlägt die Anfrage fehl, wird zusätzlich fullscreenerror ausgelöst.

Parameter

Name	Typ	Default	Beschreibung
$options	FullscreenOptions	{ navigationUI: "auto" }	Optionales Objekt mit folgenden Eigenschaften: `navigationUI` (`"auto"` \| `"show"` \| `"hide"`) ist ein Hinweis, ob die Navigationsleiste des Browsers sichtbar bleiben soll. `screen` (`ScreenDetailed`, experimentell) gibt an, auf welchem Bildschirm das Element erscheinen soll (Window Management API).

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald der Vollbildmodus aktiv ist. Verweigert der Browser die Anfrage, wird es mit einem TypeError abgelehnt (z. B. ohne Nutzeraktivierung, bei einem nicht verbundenen Element oder durch eine Permissions-Policy).

Beispiele

Video per Klick im Vollbild abspielen

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

button.addEventListener('click', async () => {
  try {
    await video.requestFullscreen({ navigationUI: 'hide' });
    console.log('Vollbild aktiv:', document.fullscreenElement === video);
  } catch (err) {
    console.error(`Vollbild abgelehnt: ${err.message}`);
  }
});

Vollbild aktiv: true

Vollbild umschalten (Toggle)

const toggleFullscreen = async (element) => {
  if (!document.fullscreenElement) {
    await element.requestFullscreen();
  } else {
    await document.exitFullscreen();
  }
};

const app = document.querySelector('#app');
document.addEventListener('keydown', (event) => {
  if (event.key === 'f') {
    toggleFullscreen(app).catch(console.error);
  }
});

Auf Moduswechsel reagieren

const gallery = document.querySelector('.gallery');

gallery.addEventListener('fullscreenchange', () => {
  const isFull = document.fullscreenElement === gallery;
  gallery.classList.toggle('is-fullscreen', isFull);
  console.log(isFull ? 'Vollbild betreten' : 'Vollbild verlassen');
});

gallery.addEventListener('fullscreenerror', () => {
  console.warn('Vollbild konnte nicht aktiviert werden.');
});

document.querySelector('#open-gallery')
  .addEventListener('click', () => gallery.requestFullscreen());

Vollbild betreten

Funktionsprüfung mit Fallback für ältere Safari-Versionen

const enterFullscreen = (el) => {
  if (!document.fullscreenEnabled && !document.webkitFullscreenEnabled) {
    return Promise.reject(new Error('Vollbild wird nicht unterstützt'));
  }
  if (el.requestFullscreen) return el.requestFullscreen();
  // Älteres Safari: ohne Promise, mit Präfix
  el.webkitRequestFullscreen();
  return Promise.resolve();
};

document.querySelector('#go').addEventListener('click', () => {
  enterFullscreen(document.documentElement).catch((e) => console.log(e.message));
});

// Wichtig · Fallstricke

Nutzeraktivierung nötig: Rufen Sie die Methode beim Laden der Seite, in einem setTimeout oder nach einem langen await auf, wird das Promise mit einem TypeError abgelehnt. Behandeln Sie die Ablehnung deshalb immer mit catch.
iframes: Eingebettete Inhalte brauchen <iframe allow="fullscreen"> (früher allowfullscreen). Außerdem darf der Header Permissions-Policy: fullscreen=() den Modus nicht sperren.
Kompatibilität: Chrome, Edge, Firefox und Safari (ab 16.4 ohne Präfix) unterstützen die Methode. Ältere Safari-Versionen kennen nur webkitRequestFullscreen() ohne Promise. Auf dem iPhone ging Vollbild lange nur für <video>, und zwar über webkitEnterFullscreen().
Styling: Im Vollbild erhält das Element oft einen schwarzen Hintergrund und wird skaliert. Passen Sie das mit :fullscreen und ::backdrop an.
Sicherheit: Browser blenden beim Betreten einen Hinweis ein und lassen den Modus immer per Esc verlassen. Fälschen Sie keine Browser-Oberfläche im Vollbild, denn das gilt als Phishing-Technik und kann eine Sperre der Seite nach sich ziehen.
Ein <dialog>-Element, das mit showModal() geöffnet wurde, oder ein Popover kann nicht in den Vollbildmodus wechseln.

Siehe auch

Document.exitFullscreen() Document.fullscreenElement Document.fullscreenEnabled Element IdleDetector.requestPermission()