前回からのつづき

前回、 OPFS のファイル操作について、FileSystemWritableFileStream オブジェクトについて説明を行いました。今回は、その続きとして、FileSystemSyncAccessHandle オブジェクトから説明していきたいと思います。

FileSystemSyncAccessHandle オブジェクト

FileSystemSyncAccessHandle は、FileSystemWritableFileStream オブジェクトと同様に、ファイルへの書き込みを行うためのオブジェクトです。

FileSystemFileHandle オブジェクトの createSyncAccessHandle() メソッドで取得します。

FileSystemFileHandle オブジェクトの非同期処理に対し、FileSystemSyncAccessHandle オブジェクトは、同期処理を行います。

その為、このオブジェクトを使った操作は、ブラウザのイベントループ処理では、使用できません。使用には、 Web Worker が必要です。

FileSystemWritableFileStream と比較すると、

アクセス WritableFileStream SyncAccessHandle
非同期 ○ ×
Stream対応 ○ ×
seek() ○ ×
read() × ○
write() ○ ○
truncate() ○ ○
getSize() × ○
flush() × ○

FileSystemSyncAccessHandle は「ファイルストリーム」ではなく、「ランダムアクセス可能なファイルハンドル」です。

read() メソッド

ファイルの指定位置から読み込みます。

const buffer = new Uint8Array(1024);

const bytesRead =
  accessHandle.read(
    buffer,
    { at: 0 }
  );

■ パラメータ

読み込みバッファ領域：データを読み込むバッファの変数

位置オブジェクト：

{
  at: 読み込みバイト位置(先頭0)
}

■ 戻り値

実際に読み込んだバイト数

write() メソッド

指定位置へ書き込みます。

const bytes = new TextEncoder().encode("Hello");

accessHandle.write(
  bytes,
  { at: 0 }
);

■ パラメータ

書き込みバッファ領域：データを書き込むバッファ

バッファには、ArrayBufferView が指定可能です。

※　ArrayBufferView は、TypedArray , DataView の総称です。

FileSystemWritableFileStream オブジェクトの write() メソッドと違い、String や　Blob は指定できません。

位置オブジェクト：

{
  at: 読み込みバイト位置(先頭0)
}

■ 戻り値

実際に書き込んだバイト数

getSize() メソッド

現在のファイルのバイトサイズを取得します。

const size = accessHandle.getSize();

■ パラメータ

なし

■ 戻り値

現在のファイルのバイトサイズ

例えば、

Hello OPFS

を UTF-8 で保存した場合は 10 バイトなので 10 が返ります。

※ 日本語のようなマルチバイト文字を保存した場合は、文字数とファイルサイズは一致しないことがあります。

truncate() オブジェクト

ファイルサイズを変更します。

accessHandle.truncate(5);

■ パラメータ

ファイルサイズ（バイト）

■ 戻り値

undefined

例えば、現在のファイルサイズが 100 バイトの場合

accessHandle.truncate(10);

を実行すると 10 バイト以降のデータが削除されます。

逆に、

accessHandle.truncate(1000);

を実行すると 1000 バイトへ拡張されます。

flush() メソッド

変更内容を確実に保存します。

write() での書き込みは一時的にバッファに格納された後、ストレージに書き出されます。この処理は、その内容を強制的にストレージへ反映します。

accessHandle.flush();

■ パラメータ

なし

■ 戻り値

undefined

後述の close() を呼び出す際にも通常は保存されますが、複数回の書き込みで、都度、確実に保存したい場合などに利用します。

accessHandle.write(bytes1);
accessHandle.flush();
accessHandle.write(bytes2);
accessHandle.flush();
accessHandle.write(bytes3);
accessHandle.flush();

close() メソッド

ハンドルを閉じます。

accessHandle.close();

■ パラメータ

なし

■ 戻り値

undefined

👉 閉じた後は使用できません。

まとめ

  • FileSystemFileHandle はファイルを操作するための Handle オブジェクト
  • getFile() で File オブジェクトを取得できる。
  • createWritable() で FileSystemWritableFileStream を取得できる。
  • createSyncAccessHandle() で FileSystemSyncAccessHandle を取得できる。
  • File オブジェクトは読み込み担当
  • FileSystemWritableFileStream は書き込み担当
  • FileSystemSyncAccessHandle は読み書き可能だが、同期処理の為イベントループでは使用できず、 Web Worker が必要
  • remove() によりファイル削除も可能
  • 実際のファイル操作は FileSystemFileHandle を起点として行う。