FileSystemHandle.queryPermission() — Methode · JavaScript-Referenz

Signatur

FileSystemHandle.prototype.queryPermission(descriptor)

Beschreibung

queryPermission() fragt den aktuellen Berechtigungsstatus eines FileSystemFileHandle oder FileSystemDirectoryHandle ab. Die Methode ist Teil der File System Access API. Sie zeigt nie einen Dialog an. Deshalb darf man sie jederzeit aufrufen, auch ohne Nutzeraktion, etwa beim Laden der Seite.

Am häufigsten braucht man sie, wenn man mit Handles weiterarbeitet, die in IndexedDB gespeichert wurden. Nach einem Neuladen der Seite oder einem Neustart des Browsers stehen die Rechte oft wieder auf 'prompt'. Mit queryPermission() findet man heraus, ob man direkt lesen oder schreiben kann. Andernfalls muss man mit requestPermission() neu fragen, und das geht nur nach einer Nutzeraktion.

Über das Objekt descriptor legt man fest, welches Recht geprüft wird: mode: 'read' für Lesen (Standard) oder mode: 'readwrite' für Lesen und Schreiben. Beide Rechte werden getrennt vergeben. Ein Handle kann also 'granted' für 'read' liefern und gleichzeitig 'prompt' für 'readwrite'.

Parameter

Name	Typ	Default	Beschreibung
$descriptor	{ mode?: 'read' \| 'readwrite' }	{ mode: 'read' }	Optionales Objekt, das festlegt, welches Recht geprüft wird.
$descriptor.mode	'read' \| 'readwrite'	'read'	`'read'` prüft nur das Leserecht, `'readwrite'` das Lese- und Schreibrecht.

Rückgabewert

Typ

Promise<PermissionState>

Beschreibung

Ein Promise, das mit einem PermissionState erfüllt wird: 'granted' (Recht erteilt), 'denied' (Recht verweigert) oder 'prompt' (es muss mit requestPermission() gefragt werden).

Beispiele

Leserecht einer ausgewählten Datei prüfen

// Muss durch eine Nutzeraktion ausgelöst werden (z. B. einen Klick)
document.querySelector('#open').addEventListener('click', async () => {
  const [fileHandle] = await window.showOpenFilePicker();
  const status = await fileHandle.queryPermission({ mode: 'read' });
  console.log(`Leserecht: ${status}`);
});

Leserecht: granted

Hilfsfunktion: erst prüfen, nur bei Bedarf fragen

const verifyPermission = async (handle, withWrite = false) => {
  const options = { mode: withWrite ? 'readwrite' : 'read' };
  // Kein Dialog, darf jederzeit aufgerufen werden
  if ((await handle.queryPermission(options)) === 'granted') {
    return true;
  }
  // Braucht eine Nutzeraktion und zeigt eventuell einen Dialog
  if ((await handle.requestPermission(options)) === 'granted') {
    return true;
  }
  return false;
};

document.querySelector('#save').addEventListener('click', async () => {
  const handle = await window.showSaveFilePicker({ suggestedName: 'notiz.txt' });
  if (await verifyPermission(handle, true)) {
    const writable = await handle.createWritable();
    await writable.write('Hallo Welt');
    await writable.close();
    console.log('Gespeichert');
  }
});

Gespeichert

Gespeichertes Verzeichnis-Handle beim Seitenstart prüfen

// Setzt voraus, dass das Handle vorher in IndexedDB abgelegt wurde
const getStoredHandle = () => new Promise((resolve, reject) => {
  const req = indexedDB.open('app-db', 1);
  req.onupgradeneeded = () => req.result.createObjectStore('handles');
  req.onsuccess = () => {
    const tx = req.result.transaction('handles', 'readonly');
    const get = tx.objectStore('handles').get('projektordner');
    get.onsuccess = () => resolve(get.result);
    get.onerror = () => reject(get.error);
  };
  req.onerror = () => reject(req.error);
});

const dirHandle = await getStoredHandle();
if (dirHandle) {
  const state = await dirHandle.queryPermission({ mode: 'readwrite' });
  if (state === 'granted') {
    console.log(`Direkter Zugriff auf "${dirHandle.name}" möglich`);
  } else {
    // Schaltfläche anzeigen, damit der Nutzer den Zugriff erneut erlaubt
    document.querySelector('#reconnect').hidden = false;
    console.log(`Status: ${state}, Nutzeraktion nötig`);
  }
}

Status: prompt, Nutzeraktion nötig

// Wichtig · Fallstricke

Browser-Unterstützung: Die Methode gibt es nur in Chromium-Browsern (Chrome, Edge, Opera, ab Version 86). Firefox und Safari unterstützen zwar das Origin Private File System (navigator.storage.getDirectory()), aber nicht queryPermission(). Deshalb vor der Nutzung prüfen: 'queryPermission' in FileSystemHandle.prototype.
Nur in sicheren Kontexten: Die Methode funktioniert nur über HTTPS oder auf localhost, und nicht in allen iframes über Ursprungsgrenzen hinweg.
Status kann veralten: Das Ergebnis gilt nur für den Moment der Abfrage. Der Nutzer kann Rechte jederzeit in den Website-Einstellungen entziehen. Operationen wie getFile() oder createWritable() sollten deshalb trotzdem mit try/catch abgesichert werden (möglicher Fehler: NotAllowedError).
Nicht mit requestPermission() verwechseln: queryPermission() zeigt nie einen Dialog. requestPermission() dagegen braucht eine Nutzeraktion (transient user activation).
Rechte nach dem Neuladen: Handles aus IndexedDB haben nach einem Neuladen meist den Status 'prompt'. Neuere Chrome-Versionen (ab 122) bieten optional dauerhafte Rechte an.
Das Recht 'readwrite' schließt Lesen mit ein. Umgekehrt gilt das nicht.

Siehe auch

Permissions.query() DeviceOrientationEvent.requestPermission() FileSystemHandle.requestPermission() FileSystemHandle.remove() FileSystemHandle.isSameEntry()