PermissionStatus.state — Eigenschaft · JavaScript-Referenz

Signatur

PermissionStatus.state

Beschreibung

Die Eigenschaft state eines PermissionStatus-Objekts gibt an, in welchem Zustand sich eine bestimmte Berechtigung (z. B. geolocation, notifications, camera) gerade befindet. Das Objekt bekommt man über navigator.permissions.query({ name }).

Mögliche Werte:

"granted": Die Berechtigung wurde erteilt, die zugehörige API lässt sich ohne Rückfrage nutzen.
"denied": Die Berechtigung wurde verweigert, Aufrufe der API schlagen fehl, und es erscheint keine Rückfrage mehr.
"prompt": Es wurde noch nicht entschieden. Beim nächsten Aufruf der API fragt der Browser den Nutzer.

Typischer Einsatz: die Oberfläche vorab passend gestalten, z. B. einen „Standort freigeben“-Button nur bei "prompt" zeigen, bei "denied" stattdessen einen Hinweis auf die Browsereinstellungen einblenden. Der Wert ist live: Ändert der Nutzer die Berechtigung, aktualisiert sich state, und am PermissionStatus wird das Ereignis change ausgelöst.

Wichtig: state fordert selbst keine Berechtigung an und löst keine Rückfrage aus. Die eigentliche Anfrage geschieht erst beim Aufruf der jeweiligen API (z. B. getCurrentPosition() oder Notification.requestPermission()).

Rückgabewert

Typ

"granted" | "denied" | "prompt"

Beschreibung

Ein String mit dem aktuellen Zustand der Berechtigung. Nur lesbar: Zuweisungen werden ignoriert bzw. werfen im Strict Mode einen TypeError.

Beispiele

Zustand der Standort-Berechtigung abfragen

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

Geolocation: prompt

Oberfläche je nach Zustand anpassen

const updateUI = (state) => {
  const button = document.querySelector('#locate');
  const hint = document.querySelector('#hint');
  button.hidden = state === 'denied';
  hint.textContent = {
    granted: 'Standort ist freigegeben.',
    prompt: 'Klicke, um deinen Standort freizugeben.',
    denied: 'Standortzugriff blockiert. Bitte in den Browsereinstellungen erlauben.'
  }[state];
};

const status = await navigator.permissions.query({ name: 'geolocation' });
updateUI(status.state);

// Auf spätere Änderungen durch den Nutzer reagieren
status.addEventListener('change', () => updateUI(status.state));

Mehrere Berechtigungen mit Fehlerbehandlung prüfen

const checkPermission = async (name) => {
  try {
    const { state } = await navigator.permissions.query({ name });
    return state;
  } catch (err) {
    // Name wird von diesem Browser nicht unterstützt
    return `nicht unterstützt (${err.name})`;
  }
};

for (const name of ['notifications', 'camera', 'microphone', 'clipboard-read']) {
  console.log(name, '→', await checkPermission(name));
}

notifications → prompt camera → granted microphone → denied clipboard-read → nicht unterstützt (TypeError)

Benachrichtigungen nur anfragen, wenn sinnvoll

const enableNotifications = async () => {
  const { state } = await navigator.permissions.query({ name: 'notifications' });
  if (state === 'granted') return true;
  if (state === 'denied') {
    console.warn('Benachrichtigungen blockiert.');
    return false;
  }
  // state === 'prompt' → jetzt tatsächlich anfragen
  return (await Notification.requestPermission()) === 'granted';
};

document.querySelector('#notify').addEventListener('click', enableNotifications);

// Wichtig · Fallstricke

Unterstützte Namen unterscheiden sich: Welche name-Werte query() akzeptiert, hängt vom Browser ab (z. B. camera/microphone in Firefox erst spät, clipboard-read nur in Chromium). Nicht unterstützte Namen führen zu einem abgelehnten Promise (TypeError), deshalb immer mit try/catch absichern.
Safari: Die Permissions API gibt es erst ab Safari 16. Vorher per 'permissions' in navigator prüfen.
Kein Ersatz für die eigentliche Anfrage: "granted" garantiert nicht, dass die API funktioniert (z. B. kann GPS-Hardware fehlen). Fehlerfälle der Ziel-API trotzdem behandeln.
Browserspezifisches Verhalten: Manche Browser melden nach einmaligem Schließen der Rückfrage weiter "prompt" oder setzen erteilte Berechtigungen nach einiger Zeit wieder zurück (einmalige bzw. temporäre Freigaben). Den Wert daher nicht dauerhaft zwischenspeichern, sondern das change-Ereignis nutzen.
Nur in sicheren Kontexten (HTTPS) verlässlich. In iframes hängt der Zustand zusätzlich von der Permissions-Policy bzw. dem allow-Attribut ab.
Die frühere Eigenschaft PermissionStatus.status ist veraltet und wurde entfernt. Nur noch state verwenden.

Siehe auch

Permissions.query() Navigator.permissions PerformanceTiming.fetchStart PermissionStatus.name XRSession.renderState