Document.featurePolicy — Eigenschaft · JavaScript-Referenz

Signatur

get Document.featurePolicy

Beschreibung

document.featurePolicy gibt ein FeaturePolicy-Objekt zurück. Darüber lässt sich zur Laufzeit abfragen, welche mächtigen Browser-Funktionen – etwa camera, microphone, geolocation, fullscreen oder autoplay – im aktuellen Dokument erlaubt sind. Die Richtlinie ergibt sich aus dem HTTP-Header Permissions-Policy (früher Feature-Policy) und bei eingebetteten Dokumenten zusätzlich aus dem allow-Attribut des übergeordneten <iframe>.

Das Objekt stellt vier Methoden bereit:

allowsFeature(feature[, origin]) – gibt true zurück, wenn die Funktion für das Dokument oder für einen bestimmten Ursprung (Origin) erlaubt ist.
features() – listet alle Funktionsnamen auf, die der Browser kennt.
allowedFeatures() – listet alle Funktionen auf, die im aktuellen Kontext erlaubt sind.
getAllowlistForFeature(feature) – liefert die Liste der erlaubten Ursprünge für eine Funktion, z. B. ["*"] oder ["https://example.com"].

Das ist vor allem für eingebettete Widgets und Drittanbieter-Skripte nützlich: Sie können vorab prüfen, ob etwa Kamerazugriff überhaupt erlaubt ist, und dann eine passende Ersatzoberfläche anzeigen, statt in eine abgelehnte Berechtigungsanfrage zu laufen. Wichtig ist der Unterschied: Die Richtlinie sagt nur, ob eine Funktion grundsätzlich verwendet werden darf – nicht, ob der Nutzer die Berechtigung schon erteilt hat. Dafür gibt es die Permissions API.

Rückgabewert

Typ

FeaturePolicy | undefined

Beschreibung

Ein FeaturePolicy-Objekt für das aktuelle Dokument. In Browsern ohne Unterstützung ist die Eigenschaft nicht vorhanden, der Zugriff ergibt also undefined.

Beispiele

Unterstützung prüfen und Kamera-Erlaubnis abfragen

const policy = document.featurePolicy;

if (!policy) {
  console.log('Feature Policy API wird nicht unterstützt');
} else if (policy.allowsFeature('camera')) {
  console.log('Kamera darf in diesem Dokument genutzt werden');
} else {
  console.log('Kamera ist durch die Richtlinie gesperrt');
}

Kamera darf in diesem Dokument genutzt werden

Alle erlaubten Funktionen auflisten

if ('featurePolicy' in document) {
  const allowed = document.featurePolicy.allowedFeatures();
  console.log(`${allowed.length} Funktionen erlaubt`);
  console.log(allowed.includes('geolocation') ? 'Geolocation erlaubt' : 'Geolocation gesperrt');
}

42 Funktionen erlaubt Geolocation erlaubt

Erlaubte Ursprünge für eine Funktion ermitteln

// Server sendet z. B.: Permissions-Policy: fullscreen=(self "https://video.example.com")
const origins = document.featurePolicy?.getAllowlistForFeature('fullscreen') ?? [];
console.log(origins);

const videoOk = document.featurePolicy?.allowsFeature('fullscreen', 'https://video.example.com');
console.log('Vollbild für Video-Anbieter:', videoOk);

["https://www.meine-seite.de", "https://video.example.com"] Vollbild für Video-Anbieter: true

Richtlinie eines iframes vor dem Einbetten prüfen

const frame = document.createElement('iframe');
frame.src = 'https://widget.example.com/';
frame.allow = 'microphone';
document.body.append(frame);

// HTMLIFrameElement.featurePolicy zeigt die Richtlinie für den Inhalt des iframes
const mic = frame.featurePolicy?.allowsFeature('microphone');
console.log('Mikrofon im Widget erlaubt:', mic);

Mikrofon im Widget erlaubt: true

// Wichtig · Fallstricke

Experimentell und nicht standardisiert: Nur Chromium-basierte Browser unterstützen die Eigenschaft. Firefox (nur hinter einem Flag) und Safari bieten sie nicht an. Prüfe deshalb immer vorher mit 'featurePolicy' in document oder optionaler Verkettung (?.).
Umbenennung: Feature Policy heißt inzwischen Permissions Policy. Der Header Feature-Policy gilt als veraltet, nutze stattdessen Permissions-Policy (mit anderer Syntax). Die JavaScript-Schnittstelle heißt in Chromium weiterhin featurePolicy; eine künftige document.permissionsPolicy ist zwar vorgesehen, aber nicht verbreitet.
Richtlinie ≠ Nutzerberechtigung: allowsFeature('camera') gibt true zurück, auch wenn der Nutzer den Kamerazugriff später ablehnt. Den Berechtigungsstatus fragst du mit navigator.permissions.query() ab.
Die Rückgabe von features() hängt von Browser und Version ab. Unbekannte Funktionsnamen führen bei allowsFeature() zu false und lösen keinen Fehler aus.
Die Eigenschaft ist schreibgeschützt. Die Richtlinie lässt sich nur serverseitig über den HTTP-Header oder über das allow-Attribut von iframes festlegen, nicht per JavaScript.

Siehe auch

Permissions.query() FontFace.featureSettings Document.timeline Document.URL Document.alinkColor