FileSystemFileHandle

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since 2023年3月.

* Some parts of this feature may have varying levels of support.

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

File System Access API の FileSystemFileHandle インターフェイスは、ファイルシステムのエントリーのハンドルを表します。このインターフェイスには、window.showOpenFilePicker() メソッドを通じてアクセスします。

注意するべき点として、読み書きの操作にはファイルアクセスの許可が必要ですが、この許可は同じオリジンの他のタブが開かれていない場合、ページを再読み込みすると消滅します。FileSystemHandle インターフェイスの queryPermission メソッドを用いると、ファイルにアクセスする前に許可の状態を確かめることができます。

FileSystemHandle FileSystemFileHandle

インスタンスプロパティ

親の FileSystemHandle からプロパティを継承します。

インスタンスメソッド

親の FileSystemHandle からメソッドを継承します。

getFile()

ハンドルが表すエントリーのディスク上での状態を表す File オブジェクトで解決する Promise を返します。

createSyncAccessHandle()

ファイルを同期式で読み書きすることができる FileSystemSyncAccessHandle オブジェクトで解決する Promise を返します。このメソッドは同期式であるという性質によりパフォーマンス上有利ですが、それ用の Web Workers の中でしか用いることができません。

createWritable()

ファイルに書き込むことができる新しく作成された FileSystemWritableFileStream オブジェクトで解決する Promise を返します。

例

ファイルを読み込む

以下の非同期関数は、ファイルピッカーを表示し、ファイルが選択されると getFile() メソッドを用いて内容を取得します。

js
async function getTheFile() {
  const pickerOpts = {
    types: [
      {
        description: "Images",
        accept: {
          "image/*": [".png", ".gif", ".jpeg", ".jpg"],
        },
      },
    ],
    excludeAcceptAllOption: true,
    multiple: false,
  };

  // ファイルピッカーを開く
  const [fileHandle] = await window.showOpenFilePicker(pickerOpts);
  // ファイルの内容を得る
  const fileData = await fileHandle.getFile();
  return fileData;
}

ファイルに書き込む

以下の非同期関数は、与えられた内容をファイルハンドルに書き込むことにより、ディスクに書き込みます。

js
async function writeFile(fileHandle, contents) {
  // 書き込み先の FileSystemWritableFileStream を作成する
  const writable = await fileHandle.createWritable();

  // ファイルの内容をストリームに書き込む
  await writable.write(contents);

  // ファイルを閉じ、内容をディスクに書き込む
  await writable.close();
}

同期式でファイルを読み書きする

以下の非同期のイベントハンドラーは、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() は誤って非同期メソッドとされていました。これは現在では修正されていますが、まだ非同期バージョンをサポートしているブラウザーもあります。