FileSystemSyncAccessHandle.write()

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.

安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。

FileSystemSyncAccessHandle インターフェイスの write() メソッドは、指定のバッファーの内容をハンドルに対応するファイルに書き込みます。オフセットを指定することもできます。ArrayBuffer の内容を直接操作することはできないことに注意してください。かわりに、バッファーを指定の形式で表す Int8Array などの型付き配列オブジェクトの一つ、または DataView オブジェクトを作成し、それを用いてバッファーの内容を読み書きします。

FileSystemSyncAccessHandle.write() により行われる書き込みは in-place です。すなわち、変更は writer に書き込まれるのと同時に実際のファイルに書き込まれます。これは (FileSystemFileHandle.createWritable() などの) File System Access API で利用可能な他の書き込みの仕組みでは成り立たず、変更は書き込みストリームが閉じられるまでディスクに書き込まれません。

構文

js
write(buffer, FileSystemReadWriteOptions)

引数

buffer

ファイルに書き込むバッファーを表す ArrayBuffer または (DataView などの) ArrayBufferView です。

FileSystemReadWriteOptions 省略可

以下のプロパティを含むオプションオブジェクトです。

at

バッファーを書き込むファイルの先頭からのバイト単位のオフセットを表す数値です。

返値

ファイルに書き込まれたバイト数を表す数値で解決する Promise を返します。

例外

InvalidStateError DOMException

対応するアクセスハンドルが既に閉じられているとき投げられます。

例

以下の非同期のイベントハンドラー関数は、Web Worker の中にあります。メインスレッドからメッセージを受信すると、以下の動作をします。

  • 同期式ファイルアクセスハンドルを作成します。
  • ファイルのサイズを取得し、格納用の ArrayBuffer を作成します。
  • ファイルの内容をバッファーに読み込みます。
  • メッセージをエンコードし、ファイルの終端に書き込みます。
  • 変更をディスクに書き込み、アクセスハンドルを閉じます。
js
onmessage = async (e) => {
  // メインスクリプトからの処理対象のメッセージを取得する
  const message = e.data;

  // draft ファイルのハンドルを取得する
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // 同期式のアクセスハンドルを取得する
  const accessHandle = await draftHandle.createSyncAccessHandle();

  // ファイルのサイズを取得する
  const fileSize = accessHandle.getSize();
  // ファイルの内容をバッファーに読み込む
  const buffer = new DataView(new ArrayBuffer(fileSize));
  const readBuffer = accessHandle.read(buffer, { at: 0 });

  // メッセージをファイルの終端に書き込む
  const encoder = new TextEncoder();
  const encodedMessage = encoder.encode(message);
  const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });

  // 変更をディスクに書き込む
  accessHandle.flush();

  // 完了したら、常に FileSystemSyncAccessHandle を閉じる
  accessHandle.close();
};

メモ: 仕様書の以前のバージョンでは、close()・flush()・getSize()・truncate() は誤って非同期のメソッドとされていました。これは現在は変更されていますが、まだ非同期バージョンをサポートしているブラウザーもあります。

仕様書

Specification
File System Standard
# api-filesystemsyncaccesshandle-write

ブラウザーの互換性

BCD tables only load in the browser

関連情報