はじめに

前回は、OPFS のディレクトリ操作を担当する FileSystemDirectoryHandle オブジェクトについて解説しました。

今回は、実際にファイルを操作するための FileSystemFileHandle オブジェクトについて解説します。

ファイルへの読み込みや書き込みは、FileSystemFileHandle オブジェクトを起点として行います。

また、実際の読み書きには、

  • File
  • FileSystemWritableFileStream
  • FileSystemSyncAccessHandle

といったオブジェクトも登場します。

それでは、それぞれの役割を理解しながら見ていきたいと思います。

FileSystemFileHandle オブジェクト

FileSystemFileHandle オブジェクトは、ファイルを操作するための Handle オブジェクトです。

ディレクトリを表す FileSystemDirectoryHandle オブジェクトと同様に、FileSystemHandle オブジェクトを継承しています。

そのため、

  • name
  • kind
  • isSameEntry()

など、FileSystemDirectoryHandle オブジェクトと共通のプロパティやメソッドも利用できます。

FileSystemFileHandle オブジェクトの取得は、FileSystemDirectoryHandle オブジェクトの getFileHandle() メソッドで行います。

const root = await navigator.storage.getDirectory();

const fileHandle =
  await root.getFileHandle(
    "sample.txt",
    { create: true }
  );

name プロパティ

ファイル名を取得します。

console.log(fileHandle.name);　// 例：sample.txt

kind プロパティ

ファイル種別を取得します。常に、"file" が返されます。

console.log(fileHandle.kind); // file

getFile() メソッド

ファイル内容を取得するための File オブジェクトを返します。

const file = await fileHandle.getFile();

■ パラメータ

なし

■ 戻り値

Promise オブジェクト

await 完了後、File オブジェクト

createWritable() メソッド

非同期的にファイルへ書き込むための FileSystemWritableFileStream オブジェクトを取得します。

const writable = await fileHandle.createWritable();

■ パラメータ

なし

■ 戻り値

Promise オブジェクト

await 完了後、FileSystemWritableFileStream オブジェクト

createSyncAccessHandle() メソッド

同期的にファイルへアクセスするための FileSystemSyncAccessHandle オブジェクトを取得します。

OPFS 専用のメソッドです。

const accessHandle = await fileHandle.createSyncAccessHandle();

■ パラメータ

なし

■ 戻り値

Promise オブジェクト

await 完了後、FileSystemSyncAccessHandle オブジェクト

※ 本メソッドで取得できる FileSystemSyncAccessHandle オブジェクトを使用した同期的な書き込みは、ブラウザのJavaScript のイベントループの中では使用できません。ループ処理をブロックしてしまうからです。使用には、 Web Worker が必要です。

remove() メソッド

ファイル自身を削除します。

await fileHandle.remove();

■ パラメータ

なし

■ 戻り値

Promise オブジェクト

await 完了後、undefined

👉 ただし、ブラウザによって実装状況に差があるため注意が必要です。

互換性を重視する場合は、

await dirHandle.removeEntry("sample.txt");

を利用する方が安全です。

isSameEntry() メソッド

FileSystemHandle から継承されたメソッドです。2つの Handle が同じファイル（またはディレクトリ）を指しているか判定できます。

const result =　await fileHandle1.isSameEntry(fileHandle2);

■ パラメータ

比較する別の FileSystemFileHandle オブジェクト

■ 戻り値

Promise オブジェクト

await 完了後、同じであれば true 違っていれば false

👉 FileSystemFileHandle は FileSystemHandle を継承しているため、isSameEntry() も利用できますが、日常的に使う機会はそれほど多くありません。

File オブジェクト

getFile() メソッドで取得できるオブジェクトです。

const file =　await fileHandle.getFile();

ファイル内容の読み込みを担当します。

File は、Blob の派生クラスです。

👉 File オブジェクトは Blob を継承しているため、 slice() など Blob の機能も利用できます。

text() メソッド

テキストとして読み込みます。

const text = await file.text();

■ パラメータ

なし

■ 戻り値

Promise オブジェクト

await 完了後、読み込んだ文字列

arrayBuffer() メソッド

ArrayBuffer として取得します。

画像や音声などのバイナリデータを扱う場合によく利用されます。

const buffer = await file.arrayBuffer();

console.log(buffer.byteLength);

■ パラメータ

なし

■ 戻り値

Promise オブジェクト

await 完了後、ArrayBuffer オブジェクト

Uint8Arrayへ変換する例

const buffer = await file.arrayBuffer();

const bytes = new Uint8Array(buffer);

※ bytes は、見た目だけのオブジェクトであり、実態は、buffer と同一のものを指しています。

stream() メソッド

ReadableStream オブジェクトを取得します。

const stream = file.stream();

■ パラメータ

なし

■ 戻り値

ReadableStream オブジェクト

👉 巨大なファイルを扱う場合に利用されます。

（つづく）