FileSystemHandle.requestPermission() — Methode · JavaScript-Referenz

Signatur

FileSystemHandle.prototype.requestPermission(descriptor)

Beschreibung

requestPermission() gehört zur File System Access API. Die Methode fragt den Benutzer, ob die Webanwendung ein bestimmtes FileSystemFileHandle oder FileSystemDirectoryHandle lesen (mode: "read") oder lesen und beschreiben (mode: "readwrite") darf. Ist das Recht schon erteilt, löst das Promise sofort mit "granted" auf. Ein Dialog erscheint dann nicht.

Gebraucht wird die Methode vor allem, wenn ein Handle wiederverwendet wird. Das ist etwa der Fall, wenn es in IndexedDB gespeichert war und nach einem Neuladen der Seite wieder geladen wird. Die Rechte aus der ursprünglichen Dateiauswahl (showOpenFilePicker(), showDirectoryPicker()) gelten meist nur für die laufende Sitzung. Außerdem erteilt ein Picker zunächst oft nur Leserechte. Vor dem ersten Schreibzugriff müssen dann "readwrite"-Rechte angefordert werden.

Üblich ist diese Reihenfolge: Zuerst mit queryPermission() ohne Dialog den aktuellen Status prüfen. Nur wenn er nicht "granted" ist, requestPermission() aufrufen. Der Aufruf braucht eine vorübergehende Benutzeraktivierung (transient user activation), muss also z. B. direkt in einem Klick-Handler passieren.

Parameter

Name	Typ	Default	Beschreibung
$descriptor	{ mode?: "read" \| "readwrite" }	{ mode: "read" }	Optionales Objekt mit der Eigenschaft `mode`: `"read"` für reine Leserechte oder `"readwrite"` für Lese- und Schreibrechte.

Rückgabewert

Typ

Promise<"granted" | "denied" | "prompt">

Beschreibung

Promise, das mit einem PermissionState auflöst: "granted" (erteilt), "denied" (abgelehnt) oder "prompt" (Dialog geschlossen, ohne zu entscheiden). Es wird mit einem SecurityError-DOMException abgelehnt, wenn keine Benutzeraktivierung vorliegt, und mit TypeError bei einem ungültigen mode.

Beispiele

Hilfsfunktion: Berechtigung prüfen und bei Bedarf anfordern

// Gibt true zurück, wenn der Zugriff im gewünschten Modus erlaubt ist
const verifyPermission = async (handle, readWrite = false) => {
  const options = { mode: readWrite ? 'readwrite' : 'read' };

  // 1. Ohne Dialog prüfen
  if ((await handle.queryPermission(options)) === 'granted') {
    return true;
  }
  // 2. Benutzer fragen (braucht eine Benutzeraktivierung)
  if ((await handle.requestPermission(options)) === 'granted') {
    return true;
  }
  return false;
};

Datei nach dem Speichern in IndexedDB wieder öffnen

// Setzt voraus, dass 'handle' vorher per showOpenFilePicker() geholt
// und in IndexedDB gespeichert wurde (z. B. mit der Bibliothek idb-keyval)
const reopenButton = document.querySelector('#reopen');

reopenButton.addEventListener('click', async () => {
  const handle = await loadHandleFromIndexedDB(); // eigene Funktion
  if (!handle) return;

  const state = await handle.requestPermission({ mode: 'read' });
  if (state !== 'granted') {
    console.warn('Zugriff verweigert:', state);
    return;
  }

  const file = await handle.getFile();
  console.log(`Geöffnet: ${file.name} (${file.size} Bytes)`);
});

Geöffnet: notizen.txt (1024 Bytes)

Schreibrechte anfordern und Datei speichern

const saveButton = document.querySelector('#save');
let fileHandle;

saveButton.addEventListener('click', async () => {
  if (!fileHandle) {
    [fileHandle] = await window.showOpenFilePicker();
  }

  const state = await fileHandle.requestPermission({ mode: 'readwrite' });
  if (state !== 'granted') {
    alert('Ohne Schreibrecht kann nicht gespeichert werden.');
    return;
  }

  const writable = await fileHandle.createWritable();
  await writable.write('Neuer Inhalt – gespeichert am ' + new Date().toLocaleString('de-DE'));
  await writable.close();
  console.log('Datei gespeichert');
});

Datei gespeichert

// Wichtig · Fallstricke

Browser-Kompatibilität: 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 weder requestPermission() noch queryPermission(). Deshalb vorher die Unterstützung prüfen: 'requestPermission' in FileSystemHandle.prototype.
Benutzeraktivierung nötig: Wird die Methode ohne Benutzeraktion aufgerufen, etwa beim Laden der Seite, endet das mit einem SecurityError. Nach längerem await (z. B. auf einen Netzwerkaufruf) kann die Aktivierung schon abgelaufen sein. Darum requestPermission() möglichst früh im Handler aufrufen.
Nur in sicheren Kontexten: Die Methode funktioniert nur über HTTPS oder localhost und im Top-Level-Dokument. In Cross-Origin-iframes ist sie nicht verfügbar.
Bei Handles aus dem Origin Private File System ist der Status immer "granted", ein Dialog erscheint nie.
"prompt" als Ergebnis heißt: Der Benutzer hat den Dialog geschlossen, ohne zu entscheiden. Das nicht als endgültige Ablehnung behandeln, beim nächsten Klick darf erneut gefragt werden.
Rechte für ein Verzeichnis-Handle gelten auch für alle Einträge darin.
Die Methode ist nicht Teil des WHATWG-Standards File System. Sie stammt aus dem Entwurf der WICG zur File System Access API. Ihr Verhalten kann sich also noch ändern.

Siehe auch

FileSystemHandle.queryPermission() FileSystemHandle.remove() FileSystemHandle.isSameEntry() IdleDetector.requestPermission() XRSystem.requestSession()