Permissions — Schnittstelle · JavaScript-Referenz

Signatur

interface Permissions

Beschreibung

Die Permissions-Schnittstelle ist der zentrale Einstiegspunkt der Permissions API. Man erzeugt sie nicht selbst. Stattdessen greift man über navigator.permissions (im Fenster) oder self.navigator.permissions (in Workern) auf die einzige Instanz zu.

Die wichtigste Methode ist query(permissionDescriptor). Sie gibt ein Promise zurück, das mit einem PermissionStatus-Objekt erfüllt wird. Dessen Eigenschaft state hat einen der Werte "granted", "denied" oder "prompt". Über das change-Event des Status erfährt man, wenn die Nutzerin die Berechtigung nachträglich ändert.

So kann man die Oberfläche passend gestalten, bevor eine eigentliche Berechtigungsanfrage (z. B. getCurrentPosition() oder Notification.requestPermission()) einen Dialog auslöst. Man blendet etwa einen Erklärtext ein, wenn der Status "prompt" ist, oder einen Hinweis auf die Browser-Einstellungen, wenn er "denied" ist.

Permissions.prototype.query(descriptor): fragt den aktuellen Status ab (Standard, weit unterstützt).
Permissions.prototype.revoke(descriptor): widerruft eine Berechtigung. Die Methode ist veraltet und wurde aus allen gängigen Browsern entfernt.
Permissions.prototype.request(descriptor): experimentell und kaum unterstützt.

Parameter

Name	Typ	Default	Beschreibung
$permissionDescriptor Pflicht	{ name: string, userVisibleOnly?: boolean, sysex?: boolean }		Das Objekt wird an `query()` übergeben. `name` ist z. B. `"geolocation"`, `"notifications"`, `"camera"`, `"microphone"`, `"clipboard-read"`, `"persistent-storage"`, `"push"` oder `"midi"`. `userVisibleOnly` gilt nur für `push`, `sysex` nur für `midi`.

Beispiele

Geolocation-Berechtigung abfragen

const checkGeo = async () => {
  const status = await navigator.permissions.query({ name: 'geolocation' });
  console.log(`Geolocation: ${status.state}`);
  return status.state;
};

checkGeo();

Geolocation: prompt

Auf Änderungen der Berechtigung reagieren

const watchNotifications = async () => {
  const status = await navigator.permissions.query({ name: 'notifications' });
  const update = () => {
    document.querySelector('#notify-btn').disabled = status.state === 'denied';
    console.log('Benachrichtigungen:', status.state);
  };
  update();
  // Feuert, wenn die Nutzerin die Einstellung im Browser ändert
  status.addEventListener('change', update);
};

watchNotifications();

Benachrichtigungen: granted

Robuste Abfrage mit Fallback für nicht unterstützte Namen

const getPermissionState = async (name) => {
  if (!('permissions' in navigator)) return 'unsupported';
  try {
    const { state } = await navigator.permissions.query({ name });
    return state;
  } catch (err) {
    // TypeError, wenn der Browser den Namen nicht kennt (z. B. 'camera' in älteren Firefox-Versionen)
    return 'unsupported';
  }
};

const results = await Promise.all(
  ['geolocation', 'camera', 'clipboard-read'].map(async (n) => [n, await getPermissionState(n)])
);
console.table(Object.fromEntries(results));

{ geolocation: 'prompt', camera: 'granted', clipboard-read: 'unsupported' }

// Wichtig · Fallstricke

Unterstützte Namen sind je nach Browser verschieden: Kennt ein Browser einen name nicht, wird das Promise mit TypeError abgelehnt. Frage deshalb immer mit try/catch ab. Firefox und Safari unterstützen z. B. clipboard-read nicht oder nur teilweise.
query() öffnet keinen Dialog. Die Methode liest nur den Status aus. Die eigentliche Anfrage erfolgt über die jeweilige API, z. B. Notification.requestPermission() oder getUserMedia().
revoke() ist veraltet und in aktuellen Browsern entfernt. Nutzerinnen widerrufen Berechtigungen nur selbst über die Browser-Einstellungen.
Die API ist nur in einem sicheren Kontext (HTTPS) zuverlässig verfügbar. In Workern steht sie über self.navigator.permissions bereit.
Der Status "prompt" kann auch bedeuten, dass der Browser die Entscheidung nur für die laufende Sitzung speichert. Verlasse dich nicht darauf, dass eine Berechtigung dauerhaft bestehen bleibt.

Siehe auch

Navigator.permissions Permissions.query() Geolocation PermissionStatus XRSession