HTMLIFrameElement.featurePolicy — Eigenschaft · JavaScript-Referenz

Signatur

HTMLIFrameElement.featurePolicy

Beschreibung

Die schreibgeschützte Eigenschaft featurePolicy eines <iframe>-Elements gibt ein FeaturePolicy-Objekt zurück. Damit lässt sich aus dem Elterndokument heraus prüfen, welche Browser-Funktionen (z. B. camera, geolocation, fullscreen) im eingebetteten Frame erlaubt sind. Die Einstellungen stammen aus dem allow-Attribut des iframes und dem HTTP-Header Permissions-Policy (früher Feature-Policy) des Elterndokuments.

Das Objekt bietet vier Methoden: allowsFeature(feature, origin?) prüft, ob eine Funktion erlaubt ist. features() listet alle Funktionen auf, die der Browser kennt. allowedFeatures() gibt nur die für den Frame erlaubten Funktionen zurück. getAllowlistForFeature(feature) liefert die Liste der Ursprünge, für die eine Funktion freigegeben ist.

Nützlich ist die Eigenschaft vor allem bei der Fehlersuche und bei Einbettungen von Drittanbietern, etwa Videoplayern, Zahlungs-Widgets oder Kartendiensten. Man kann damit vorab prüfen, ob ein Widget zum Beispiel Vollbild oder das Mikrofon nutzen darf, und die Oberfläche entsprechend anpassen. Die Policy wird nur gemeldet, nicht geändert. Ändern lässt sie sich über das allow-Attribut, und die neue Policy gilt erst ab der nächsten Navigation des Frames.

Rückgabewert

Typ

FeaturePolicy

Beschreibung

Ein FeaturePolicy-Objekt mit den Methoden allowsFeature(), features(), allowedFeatures() und getAllowlistForFeature(). Wird der Browser nicht unterstützt, ist die Eigenschaft undefined.

Beispiele

Prüfen, ob ein eingebettetes Video in den Vollbildmodus darf

// HTML: <iframe id="player" src="https://video.example.com/embed/42" allow="fullscreen; autoplay"></iframe>
const frame = document.getElementById('player');

if (frame.featurePolicy) {
  const darfVollbild = frame.featurePolicy.allowsFeature('fullscreen');
  const darfKamera = frame.featurePolicy.allowsFeature('camera');
  console.log('Vollbild:', darfVollbild);
  console.log('Kamera:', darfKamera);
} else {
  console.log('featurePolicy wird nicht unterstützt');
}

Vollbild: true Kamera: false

Alle erlaubten Funktionen eines Frames auflisten

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

const policy = frame?.featurePolicy;
if (policy) {
  const erlaubt = policy.allowedFeatures();
  console.log(`${erlaubt.length} von ${policy.features().length} Funktionen erlaubt`);
  console.table(erlaubt);
}

z. B. "24 von 38 Funktionen erlaubt" plus Tabelle mit Funktionsnamen

Freigabeliste für eine Funktion ermitteln

// HTML: <iframe id="map" src="https://maps.example.com" allow="geolocation https://maps.example.com"></iframe>
const mapFrame = document.getElementById('map');

const origins = mapFrame.featurePolicy?.getAllowlistForFeature('geolocation') ?? [];
console.log('Geolocation erlaubt für:', origins);

// Gezielt für einen Ursprung prüfen
const ok = mapFrame.featurePolicy?.allowsFeature('geolocation', 'https://maps.example.com');
console.log('Karte darf Standort abfragen:', ok);

Geolocation erlaubt für: ["https://maps.example.com"] Karte darf Standort abfragen: true

UI abhängig von der Policy anpassen (mit Fallback)

const frame = document.querySelector('#payment-widget');
const button = document.querySelector('#fullscreen-btn');

// Ohne Unterstützung optimistisch annehmen, dass es erlaubt ist
const supportsCheck = 'featurePolicy' in HTMLIFrameElement.prototype;
const allowed = supportsCheck
  ? frame.featurePolicy.allowsFeature('fullscreen')
  : true;

button.hidden = !allowed;

// Wichtig · Fallstricke

Experimentell und nicht standardisiert: Die API gibt es nur in Chromium-basierten Browsern. Firefox und Safari kennen sie nicht. Prüfe deshalb immer vorher, z. B. mit 'featurePolicy' in HTMLIFrameElement.prototype oder mit optionaler Verkettung (?.).
Umbenennung: Die Spezifikation heißt inzwischen Permissions Policy, der HTTP-Header Permissions-Policy. Die JavaScript-API wurde nicht umbenannt und kann sich künftig noch ändern oder wegfallen.
Keine Live-Änderung: Wenn du das allow-Attribut änderst, gilt die neue Policy für den Frame-Inhalt erst nach dem nächsten Laden. featurePolicy kann trotzdem schon den neuen deklarierten Zustand melden.
Kein Ersatz für eine Berechtigungsprüfung: Wenn allowsFeature() true liefert, heißt das nur, dass die Policy die Funktion erlaubt. Die Nutzerin oder der Nutzer muss trotzdem noch zustimmen, etwa über den Kamera-Dialog. Den tatsächlichen Berechtigungsstatus liefert navigator.permissions.query().
Unbekannte Funktionsnamen führen nicht zu einem Fehler, sondern liefern einfach false. Das betrifft auch Tippfehler.
Die Policy im Dokument selbst liest man über document.featurePolicy aus, die des Frames über diese Eigenschaft.

Siehe auch

Permissions.query() HTMLIFrameElement.name HTMLIFrameElement.referrerPolicy HTMLIFrameElement.srcdoc HTMLIFrameElement.allow