HTMLIFrameElement.allowFullscreen — Eigenschaft · JavaScript-Referenz

Signatur

HTMLIFrameElement.allowFullscreen

Beschreibung

Die Eigenschaft allowFullscreen des HTMLIFrameElement-Interfaces spiegelt das HTML-Attribut allowfullscreen wider. Ist sie true, darf das im iframe geladene Dokument Element.requestFullscreen() aufrufen, zum Beispiel für eingebettete Videoplayer (YouTube, Vimeo), Präsentationen oder Browser-Spiele.

Weil es ein boolesches Attribut ist, kommt es nur darauf an, ob es vorhanden ist. Wer allowFullscreen = true setzt, fügt das Attribut hinzu, false entfernt es. Selbst allowfullscreen="false" im Markup ergibt true, da das Attribut ja vorhanden ist.

Heute gilt allowfullscreen als Legacy-Attribut. Empfohlen ist die Permissions Policy über das Attribut allow="fullscreen". Intern entspricht allowfullscreen der Angabe allow="fullscreen *". Gibt es beide Attribute, hat allow Vorrang.

Wichtig: Eine Änderung der Eigenschaft wirkt sich erst beim nächsten Laden des iframe-Inhalts aus. Die Berechtigung wird nämlich beim Navigieren festgelegt. Wenn du das Attribut also nachträglich setzt, musst du das iframe neu laden, zum Beispiel indem du src neu zuweist.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Attribut allowfullscreen vorhanden ist, sonst false. Beim Setzen wird das Attribut hinzugefügt (true) oder entfernt (false).

Beispiele

Wert auslesen und Attribut-Spiegelung prüfen

// <iframe id="player" src="https://www.youtube.com/embed/xyz" allowfullscreen></iframe>
const frame = document.getElementById('player');

console.log(frame.allowFullscreen);            // true
frame.allowFullscreen = false;
console.log(frame.hasAttribute('allowfullscreen')); // false

true false

Video-Embed dynamisch mit Vollbild-Erlaubnis erzeugen

const createVideoEmbed = (url, container) => {
  const iframe = document.createElement('iframe');
  iframe.width = '640';
  iframe.height = '360';
  // Legacy-Attribut plus moderne Permissions Policy
  iframe.allowFullscreen = true;
  iframe.allow = 'fullscreen; picture-in-picture';
  iframe.src = url; // erst NACH den Berechtigungen setzen
  container.append(iframe);
  return iframe;
};

const embed = createVideoEmbed('https://player.vimeo.com/video/76979871', document.body);
console.log(embed.outerHTML.includes('allowfullscreen'));

true

Nachträglich aktivieren – iframe neu laden

const frame = document.querySelector('iframe.demo');

const enableFullscreen = () => {
  if (frame.allowFullscreen) return;
  frame.allowFullscreen = true;
  // Berechtigung greift erst beim nächsten Laden
  const src = frame.src;
  frame.src = 'about:blank';
  frame.addEventListener('load', () => { frame.src = src; }, { once: true });
};

enableFullscreen();

Im eingebetteten Dokument prüfen, ob Vollbild erlaubt ist

// Code innerhalb des iframe-Dokuments
const btn = document.querySelector('#fullscreen-btn');

btn.hidden = !document.fullscreenEnabled;

btn.addEventListener('click', async () => {
  try {
    await document.documentElement.requestFullscreen();
  } catch (err) {
    console.warn('Vollbild abgelehnt:', err.message);
  }
});

// Wichtig · Fallstricke

Nur Legacy: Verwende bevorzugt allow="fullscreen" (Permissions Policy). Mit allow="fullscreen 'self'" kannst du die Erlaubnis auf bestimmte Herkünfte beschränken. allowfullscreen erlaubt dagegen jede Herkunft (*).
Kein Sofort-Effekt: Wenn du die Eigenschaft änderst, nachdem das iframe geladen ist, wirkt sich das erst nach einer erneuten Navigation des iframes aus.
Boolesches Attribut: allowfullscreen="false" im HTML bedeutet trotzdem true. Zum Deaktivieren musst du das Attribut entfernen.
Verschachtelte iframes: Jede Ebene muss Vollbild erlauben. Fehlt die Erlaubnis bei einem übergeordneten iframe, meldet document.fullscreenEnabled im inneren Dokument false.
Weitere Voraussetzungen: requestFullscreen() braucht zusätzlich eine Nutzeraktion, etwa einen Klick. Ohne sie wird das Promise abgelehnt.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Die alten Präfix-Varianten webkitallowfullscreen und mozallowfullscreen braucht man nur noch für sehr alte Browser.
Sicherheit: Vollbild lässt sich für Phishing missbrauchen, zum Beispiel mit einer gefälschten Browser-Oberfläche. Erlaube es deshalb nur vertrauenswürdigen eingebetteten Inhalten.

Siehe auch

HTMLIFrameElement.allowPaymentRequest HTMLIFrameElement.allow HTMLIFrameElement.browsingTopics HTMLIFrameElement.contentDocument HTMLIFrameElement.loading