FileSystemWritableFileStream.truncate() — Methode · JavaScript-Referenz

Signatur

FileSystemWritableFileStream.prototype.truncate(size)

Beschreibung

truncate() setzt die Länge der Datei, auf die ein FileSystemWritableFileStream schreibt, auf genau size Bytes. Ist size kleiner als die aktuelle Dateigröße, wird alles dahinter abgeschnitten. Ist size größer, wird die Datei am Ende mit Null-Bytes (0x00) aufgefüllt.

Die Methode kommt vor allem dann zum Einsatz, wenn du einen Stream mit createWritable({ keepExistingData: true }) geöffnet hast und nur einen Teil der Datei behalten willst, etwa das Ende einer Logdatei abschneiden oder Speicher für eine Datei fester Größe vorab belegen. Liegt die aktuelle Schreibposition hinter der neuen Größe, wird sie auf size zurückgesetzt. Folgende write()-Aufrufe schreiben dann an das neue Dateiende.

Wie alle Schreiboperationen landet auch truncate() zunächst in einer temporären Datei. Die Originaldatei ändert sich erst, wenn du den Stream mit close() schließt. Bei abort() wird die Änderung verworfen. truncate(size) macht dasselbe wie write({ type: "truncate", size }).

Parameter

Name	Typ	Default	Beschreibung
$size Pflicht	number		Neue Dateigröße in Bytes (ganze Zahl ≥ 0). Kleinere Werte kürzen die Datei, größere füllen sie mit Null-Bytes auf.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Größenänderung im Stream vorgemerkt ist. Die Originaldatei ändert sich erst beim close().

Beispiele

Datei im Origin Private File System auf 5 Bytes kürzen

const root = await navigator.storage.getDirectory();
const handle = await root.getFileHandle('notiz.txt', { create: true });

// Erst Inhalt schreiben
let writable = await handle.createWritable();
await writable.write('Hallo Welt!');
await writable.close();

// Bestehende Daten behalten und kürzen
writable = await handle.createWritable({ keepExistingData: true });
await writable.truncate(5);
await writable.close();

const file = await handle.getFile();
console.log(await file.text(), file.size);

Hallo 5

Speicher vorab belegen und dann gezielt schreiben

const root = await navigator.storage.getDirectory();
const handle = await root.getFileHandle('puffer.bin', { create: true });
const writable = await handle.createWritable();

// 1 KiB mit Null-Bytes reservieren
await writable.truncate(1024);
// An Position 100 vier Bytes schreiben
await writable.write({ type: 'write', position: 100, data: new Uint8Array([1, 2, 3, 4]) });
await writable.close();

const file = await handle.getFile();
console.log(file.size);

1024

Letzte Zeile einer Logdatei entfernen (vom Nutzer gewählte Datei)

const [handle] = await window.showOpenFilePicker();
const file = await handle.getFile();
const text = await file.text();

const lastBreak = text.trimEnd().lastIndexOf('\n');
const newSize = new TextEncoder().encode(text.slice(0, lastBreak + 1)).length;

const writable = await handle.createWritable({ keepExistingData: true });
try {
  await writable.truncate(newSize);
  await writable.close();
} catch (err) {
  await writable.abort(); // Änderungen verwerfen
  console.error('Kürzen fehlgeschlagen:', err.name);
}

// Wichtig · Fallstricke

Ohne keepExistingData: true startet der Stream mit einer leeren Datei. truncate() vergrößert sie dann nur mit Null-Bytes, denn der alte Inhalt ist nicht mehr da.
Größe in Bytes, nicht in Zeichen: Bei UTF-8-Text sind Umlaute und Emojis mehrere Bytes lang. Berechne die Größe mit TextEncoder, sonst wird mitten in einem Zeichen abgeschnitten.
Änderungen werden erst mit close() übernommen. Wenn du den Stream nicht schließt, bleibt die Originaldatei unverändert.
Mögliche Fehler: NotAllowedError (Schreibrecht fehlt), QuotaExceededError (die neue Größe überschreitet das Speicherkontingent), TypeError (size ist keine gültige Zahl).
Kompatibilität: gut unterstützt in Chromium-Browsern, in Firefox seit Version 111 nur für das Origin Private File System, in Safari nur eingeschränkt. showOpenFilePicker() gibt es nur in Chromium. Die Methode funktioniert nur in sicheren Kontexten.
In Workern ist für das Origin Private File System die synchrone Variante FileSystemSyncAccessHandle.truncate() meist schneller.

Siehe auch

FileSystemDirectoryReader.readEntries() FileSystemWritableFileStream.write() FileSystemWritableFileStream.seek() FileSystemSyncAccessHandle.truncate() FileSystemFileEntry.file()