FileSystemSyncAccessHandle: read()-Methode

Baseline 2023

Newly available

Since March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Hinweis: Diese Funktion ist nur in Dedicated Web Workers verfügbar.

Die read()-Methode des FileSystemSyncAccessHandle-Interfaces liest den Inhalt der Datei, die mit dem Handle verknüpft ist, in einen angegebenen Puffer, optional an einem bestimmten Offset.

Syntax

js
read(buffer, options)

Parameter

buffer

Ein ArrayBuffer oder ArrayBufferView (wie ein DataView), der den Puffer darstellt, in den der Dateiinhalt gelesen werden soll. Beachten Sie, dass Sie die Inhalte eines ArrayBuffer nicht direkt manipulieren können. Stattdessen erstellen Sie eines der typisierten Array-Objekte wie ein Int8Array oder ein DataView-Objekt, welches den Puffer in einem bestimmten Format darstellt, und verwenden dieses, um die Inhalte des Puffers zu lesen und zu schreiben.

options Optional

Ein Optionsobjekt mit den folgenden Eigenschaften:

at

Eine Zahl, die den Offset in Bytes angibt, ab dem die Datei gelesen werden soll.

Rückgabewert

Eine Zahl, die die Anzahl der aus der Datei gelesenen Bytes darstellt.

Ausnahmen

InvalidStateError DOMException

Wird ausgelöst, wenn das zugehörige Zugriffs-Handle bereits geschlossen ist.

TypeError

Wird ausgelöst, wenn das zugrunde liegende Dateisystem das Lesen der Datei vom angegebenen Dateioffset nicht unterstützt.

Beispiele

Die folgende asynchrone Ereignis-Handler-Funktion ist in einem Web Worker enthalten. Beim Empfang einer Nachricht vom Haupt-Thread:

  • Erzeugt es ein synchrones Datei-Zugriffs-Handle.
  • Ermittelt die Größe der Datei und erstellt einen ArrayBuffer, um diese zu enthalten.
  • Liest den Dateiinhalt in den Puffer.
  • Kodiert die Nachricht und schreibt sie an das Ende der Datei.
  • Persistiert die Änderungen auf der Festplatte und schließt das Zugriffs-Handle.
js
onmessage = async (e) => {
  // Retrieve message sent to work from main script
  const message = e.data;

  // Get handle to draft file
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // Get sync access handle
  const accessHandle = await draftHandle.createSyncAccessHandle();

  // Get size of the file.
  const fileSize = accessHandle.getSize();
  // Read file content to a buffer.
  const buffer = new DataView(new ArrayBuffer(fileSize));
  const readBuffer = accessHandle.read(buffer, { at: 0 });

  // Write the message to the end of the file.
  const encoder = new TextEncoder();
  const encodedMessage = encoder.encode(message);
  const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });

  // Persist changes to disk.
  accessHandle.flush();

  // Always close FileSystemSyncAccessHandle if done.
  accessHandle.close();
};

Hinweis: In früheren Versionen der Spezifikation wurden close(), flush(), getSize() und truncate() fälschlicherweise als asynchrone Methoden angegeben, und ältere Versionen einiger Browser implementieren sie auf diese Weise. Allerdings implementieren alle aktuellen Browser, die diese Methoden unterstützen, sie als synchrone Methoden.

Spezifikationen

Specification
File System Standard
# api-filesystemsyncaccesshandle-read

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch