Signatur
Beschreibung
Mit navigator.permissions.query() finden Sie heraus, welchen Status eine Berechtigung wie Standort, Benachrichtigungen, Kamera oder Mikrofon im aktuellen Kontext hat. Dabei wird kein Berechtigungsdialog angezeigt. Die Methode liest den Status nur aus. Sie eignet sich deshalb gut, um die Oberfläche anzupassen, bevor Sie eine Berechtigung tatsächlich anfordern. So können Sie etwa einen Hinweis einblenden, statt direkt einen Dialog auszulösen, den der Browser später vielleicht blockiert.
Das zurückgegebene PermissionStatus-Objekt hat die Eigenschaft state mit einem der Werte "granted" (erlaubt), "denied" (abgelehnt) oder "prompt" (der Browser würde nachfragen). Außerdem ist das Objekt ein EventTarget: Über das Event change bzw. die Eigenschaft onchange erfahren Sie, wenn Nutzer die Berechtigung später in den Browser-Einstellungen ändern.
Die Methode steht über navigator.permissions im Fenster und in Web Workern (WorkerNavigator.permissions) zur Verfügung. Welche Namen im Deskriptor erlaubt sind, hängt vom Browser ab. Ein nicht unterstützter Name führt zu einem abgelehnten Promise mit einem TypeError.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $permissionDescriptor Pflicht | PermissionDescriptor (Object) | Objekt mit der Pflicht-Eigenschaft name, z. B. "geolocation", "notifications", "camera", "microphone", "clipboard-read", "persistent-storage", "push", "midi". Je nach Berechtigung gibt es weitere Felder: userVisibleOnly (boolean, für push), sysex (boolean, für midi). |
Rückgabewert
PermissionStatus-Objekt erfüllt wird. Es enthält state ("granted" | "denied" | "prompt"), name und das Event change. Bei einem unbekannten oder nicht unterstützten name wird das Promise mit einem TypeError abgelehnt.Beispiele
Standort-Berechtigung prüfen, bevor die Position abgefragt wird
const checkGeolocation = async () => {
const status = await navigator.permissions.query({ name: 'geolocation' });
switch (status.state) {
case 'granted':
navigator.geolocation.getCurrentPosition((pos) => {
console.log('Position:', pos.coords.latitude, pos.coords.longitude);
});
break;
case 'prompt':
console.log('Nutzer wird beim Abruf gefragt – erst Hinweis anzeigen.');
break;
case 'denied':
console.log('Standort blockiert – bitte in den Browser-Einstellungen freigeben.');
break;
}
};
checkGeolocation();Auf spätere Änderungen der Berechtigung reagieren
const status = await navigator.permissions.query({ name: 'notifications' });
console.log(`Aktueller Status: ${status.state}`);
const onChange = () => {
console.log(`Benachrichtigungen jetzt: ${status.state}`);
document.querySelector('#notify-btn').disabled = status.state === 'denied';
};
status.addEventListener('change', onChange);
// Alternativ: status.onchange = onChange;
// Aufräumen, wenn nicht mehr benötigt
// status.removeEventListener('change', onChange);Robuste Abfrage mit Feature-Erkennung und Fehlerbehandlung
const getPermissionState = async (name) => {
if (!('permissions' in navigator)) return 'unsupported';
try {
const { state } = await navigator.permissions.query({ name });
return state;
} catch (err) {
// z. B. TypeError, wenn der Browser den Namen nicht kennt
console.warn(`Berechtigung "${name}" nicht abfragbar:`, err.message);
return 'unsupported';
}
};
const names = ['camera', 'microphone', 'clipboard-read'];
const results = await Promise.all(names.map(getPermissionState));
console.table(Object.fromEntries(names.map((n, i) => [n, results[i]])));Push-Berechtigung mit Zusatzoption abfragen
const pushStatus = await navigator.permissions.query({
name: 'push',
userVisibleOnly: true
});
console.log('Push:', pushStatus.state);// Wichtig · Fallstricke
- Unterstützte Namen unterscheiden sich stark: Firefox und Safari kennen z. B.
"camera","microphone"oder"clipboard-read"teilweise nicht oder erst seit neueren Versionen. Nicht unterstützte Namen führen zu einemTypeError. Rufen Sie die Methode deshalb immer intry/catchauf. - Kein Dialog:
query()fordert nie eine Berechtigung an. Dafür brauchen Sie die jeweilige API, etwaNotification.requestPermission(),getUserMedia()odergeolocation.getCurrentPosition(). - Status kann abweichen: Manche Browser melden
"prompt", obwohl die Berechtigung nur für die aktuelle Sitzung erteilt wurde, oder sie melden aus Datenschutzgründen einen allgemeinen Status. Verlassen Sie sich nicht allein darauf, sondern behandeln Sie auch Fehler der eigentlichen API. - Sicherer Kontext: Viele Berechtigungen gibt es nur unter HTTPS. In iframes können Permissions-Policy-Header (
Permissions-Policy) den Status auf"denied"setzen. Permissions.revoke()ist veraltet und wird kaum unterstützt. Berechtigungen entziehen kann nur der Nutzer selbst.