FileSystemSyncAccessHandle.write() — Methode · JavaScript-Referenz

Signatur

FileSystemSyncAccessHandle.prototype.write(buffer, options)

Beschreibung

Die Methode write() von FileSystemSyncAccessHandle schreibt Bytes aus einem Puffer synchron in eine Datei des Origin Private File System (OPFS). Sie gibt die Anzahl der geschriebenen Bytes direkt zurück, ohne Promise. Deshalb eignet sie sich gut für leistungskritische Aufgaben wie SQLite-Datenbanken in WebAssembly, eigene Speicher-Engines oder Log-Dateien, die häufig beschrieben werden.

Ohne options.at schreibt write() ab der aktuellen Position des Dateizeigers. Dieser Zeiger steht anfangs bei 0 und rückt nach jedem Lese- oder Schreibvorgang um die Anzahl der verarbeiteten Bytes weiter. Mit at legst du eine absolute Byte-Position fest. Schreibst du über das Dateiende hinaus, wird die Datei entsprechend größer.

Ein FileSystemSyncAccessHandle erzeugst du nur in einem dedizierten Web Worker mit FileSystemFileHandle.createSyncAccessHandle(). Solange das Handle geöffnet ist, ist die Datei exklusiv gesperrt. Damit die Daten sicher auf dem Datenträger landen, ruf flush() auf. Ruf außerdem close() auf, sobald du fertig bist.

Parameter

Name	Typ	Default	Beschreibung
$buffer Pflicht	ArrayBuffer \| ArrayBufferView \| DataView		Die zu schreibenden Daten, z. B. ein `Uint8Array` aus `TextEncoder.encode()`.
$options	object	{}	Optionales Objekt mit Schreiboptionen.
$options.at	number	aktuelle Position des Dateizeigers	Byte-Offset, ab dem geschrieben wird. Liegt er hinter dem Dateiende, wird die Datei entsprechend größer.

Rückgabewert

Typ

number

Beschreibung

Die Anzahl der tatsächlich geschriebenen Bytes.

Beispiele

Text in eine OPFS-Datei schreiben (im Worker)

// worker.js – als dedizierter Worker starten
self.onmessage = async () => {
  const root = await navigator.storage.getDirectory();
  const fileHandle = await root.getFileHandle('notizen.txt', { create: true });
  const access = await fileHandle.createSyncAccessHandle();

  const encoder = new TextEncoder();
  const written = access.write(encoder.encode('Hallo OPFS!'), { at: 0 });

  access.flush();
  console.log('Geschrieben:', written, 'Bytes, Größe:', access.getSize());
  access.close();
};

Geschrieben: 11 Bytes, Größe: 11

Log-Einträge an das Dateiende anhängen

// worker.js
const appendLog = async (line) => {
  const root = await navigator.storage.getDirectory();
  const handle = await root.getFileHandle('app.log', { create: true });
  const access = await handle.createSyncAccessHandle();
  try {
    const data = new TextEncoder().encode(`${new Date().toISOString()} ${line}\n`);
    // An das aktuelle Dateiende anhängen
    access.write(data, { at: access.getSize() });
    access.flush();
  } finally {
    access.close(); // Sperre immer freigeben
  }
};

await appendLog('Worker gestartet');
await appendLog('Daten synchronisiert');

Dateizeiger: aufeinanderfolgende Schreibvorgänge ohne at

// worker.js
const root = await navigator.storage.getDirectory();
const handle = await root.getFileHandle('zahlen.bin', { create: true });
const access = await handle.createSyncAccessHandle();
access.truncate(0);

// Ohne 'at' schreibt write() ab der aktuellen Zeigerposition weiter
access.write(new Uint8Array([1, 2, 3]));
access.write(new Uint8Array([4, 5]));

const result = new Uint8Array(access.getSize());
access.read(result, { at: 0 });
console.log(Array.from(result));
access.close();

[1, 2, 3, 4, 5]

// Wichtig · Fallstricke

Nur in dedizierten Web Workern verfügbar: Im Haupt-Thread, in Shared Workern und in Service Workern gibt es createSyncAccessHandle() nicht. Dort nimmst du stattdessen FileSystemWritableFileStream.
Synchrone Rückgabe: In älteren Chromium-Versionen (vor 108) gaben write(), flush(), getSize() und weitere Methoden noch ein Promise zurück. Nach aktueller Spezifikation sind alle synchron.
Fehler: InvalidStateError, wenn das Handle schon geschlossen ist. QuotaExceededError, wenn der Speicherplatz des Ursprungs nicht ausreicht.
Exklusive Sperre: Solange ein Handle offen ist, schlagen weitere createSyncAccessHandle()-Aufrufe für dieselbe Datei mit NoModificationAllowedError fehl. Schließ das Handle deshalb immer in einem finally-Block.
Überschreiben: write() kürzt die Datei nicht. Sind die neuen Daten kürzer als der alte Inhalt, bleiben die restlichen alten Bytes stehen. Bei Bedarf vorher truncate() aufrufen.
Dauerhaftigkeit: Erst nach flush() ist sicher, dass die Daten dauerhaft gespeichert sind.
Das OPFS ist an den Ursprung gebunden, für Nutzer nicht sichtbar und funktioniert nur in sicheren Kontexten (HTTPS).

Siehe auch

FileSystemSyncAccessHandle FileSystemSyncAccessHandle.read() FileSystemSyncAccessHandle.flush() FileSystemSyncAccessHandle.truncate() FileSystemSyncAccessHandle.getSize() FileSystemSyncAccessHandle.close() FileSystemFileHandle.createSyncAccessHandle() StorageManager.getDirectory() FileSystemWritableFileStream