PermissionStatus — Schnittstelle · JavaScript-Referenz

Signatur

interface PermissionStatus extends EventTarget

Beschreibung

Ein PermissionStatus-Objekt bekommst du nie über einen Konstruktor. Du erhältst es als aufgelösten Wert von navigator.permissions.query({ name }). Es gibt an, ob eine Berechtigung für die aktuelle Herkunft (Origin) bereits erteilt ("granted") oder verweigert ("denied") wurde. Der dritte Zustand "prompt" bedeutet, dass der Browser beim nächsten Zugriff nachfragen würde.

Wichtige Mitglieder:

state (nur lesbar): "granted", "denied" oder "prompt".
name (nur lesbar): der Name der abgefragten Berechtigung, z. B. "geolocation".
onchange bzw. addEventListener("change", …): wird ausgelöst, sobald sich state ändert, etwa wenn die Person die Berechtigung in den Seiteneinstellungen widerruft.
Veraltet: status war der frühere Name von state und sollte nicht mehr verwendet werden.

Typischerweise prüfst du den Status, bevor du eine Funktion aufrufst, die einen Berechtigungsdialog auslöst. So kannst du die Oberfläche anpassen: bei "denied" einen Hinweis anzeigen, bei "prompt" einen erklärenden Button, bei "granted" direkt loslegen. Über das change-Ereignis bleibt die Oberfläche auch dann aktuell, wenn die Berechtigung später außerhalb der Seite geändert wird.

Rückgabewert

Typ

PermissionStatus

Beschreibung

Wird als Ergebnis des Promise von navigator.permissions.query() geliefert. Es ist ein EventTarget mit den Eigenschaften state, name und onchange.

Beispiele

Status abfragen (Instanz über query erhalten)

const checkGeo = async () => {
  // PermissionStatus-Instanz über die Permissions API erhalten
  const status = await navigator.permissions.query({ name: 'geolocation' });
  console.log(`${status.name}: ${status.state}`);
  return status;
};

checkGeo();

geolocation: prompt

UI abhängig vom Status steuern

const locateBtn = document.querySelector('#locate');
const hint = document.querySelector('#hint');

const render = (state) => {
  locateBtn.hidden = state === 'denied';
  hint.textContent = {
    granted: 'Standort wird verwendet.',
    prompt: 'Klicke auf den Button, um deinen Standort freizugeben.',
    denied: 'Standortzugriff blockiert – bitte in den Browser-Einstellungen ändern.'
  }[state];
};

const init = async () => {
  const status = await navigator.permissions.query({ name: 'geolocation' });
  render(status.state);
  // Auf spätere Änderungen reagieren (z. B. Widerruf in den Seiteneinstellungen)
  status.addEventListener('change', () => render(status.state));
};

init();

change-Ereignis per onchange und wieder entfernen

const watchNotifications = async () => {
  const status = await navigator.permissions.query({ name: 'notifications' });

  status.onchange = () => {
    console.log('Benachrichtigungen jetzt:', status.state);
  };

  // Später Überwachung beenden
  return () => { status.onchange = null; };
};

const stop = await watchNotifications();
// ... irgendwann:
stop();

Benachrichtigungen jetzt: granted

Robuste Abfrage mit Fallback

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 Berechtigungsname im Browser unbekannt ist
    return 'unsupported';
  }
};

console.log(await getPermissionState('camera'));

prompt

// Wichtig · Fallstricke

Nur abfragen, nicht anfordern: PermissionStatus löst keinen Dialog aus. Um eine Berechtigung anzufordern, rufst du die eigentliche API auf, z. B. getCurrentPosition() oder Notification.requestPermission().
Unterstützte Namen sind je nach Browser verschieden: "camera", "microphone", "clipboard-read", "midi" u. a. werden nicht überall unterstützt. Unbekannte Namen führen zu einem abgelehnten Promise mit TypeError. Deshalb immer try/catch verwenden.
Sicherer Kontext: Die Permissions API gibt es nur unter HTTPS bzw. localhost. In Web Workern wird sie nur teilweise unterstützt.
Safari: Volle Unterstützung erst ab Version 16. Ältere Versionen haben kein navigator.permissions.
Datenschutz: Manche Browser melden bei "denied" aus Schutz vor Fingerprinting weiterhin "prompt", oder sie setzen die Berechtigung nach einer Weile automatisch zurück. Verlass dich deshalb nie allein auf state, sondern behandle Fehler auch beim eigentlichen API-Aufruf.
Die veraltete Eigenschaft status solltest du nicht mehr nutzen. Verwende stattdessen state.

Siehe auch

Permissions Permissions.prototype.query() Navigator.permissions PermissionStatus.state Geolocation Notification.requestPermission()