File System Access API と Origin Private File System API はどちらも、デベロッパーがユーザーのデバイス上のファイルとディレクトリにアクセスできるようにします。前者は、デベロッパーがユーザーに表示される通常のファイル システムに対して読み取りと書き込みを行えるようにするもので、後者は、各サイトのオリジンに固有の、ユーザーには表示されない特別なファイル システムを開くもので、パフォーマンス上の利点があります。どちらの場合も、デベロッパーがファイルやディレクトリを操作する方法は FileSystemHandle オブジェクトを介します。具体的には、ファイルの場合は FileSystemFileHandle、ディレクトリの場合は FileSystemDirectoryHandle です。これまで、いずれかのファイル システムでファイルまたはディレクトリの変更を通知するには、何らかの形式のポーリングと lastModified タイムスタンプの比較、またはファイルの内容自体の比較が必要でした。
Chrome 129 から試験運用版として提供されている File System Observer API は、この状況を変え、変更が発生したときにデベロッパーに自動的にアラートを送信できるようにします。このガイドでは、この機能の仕組みと試す方法について説明します。
ユースケース
ファイル システムの変更が発生したらすぐに通知を受け取る必要があるアプリでは、File System Observer API を使用します。
- プロジェクトのファイル システム ツリーの表現を表示するウェブベースの統合開発環境（IDE）。
- ファイル システムの変更をサーバーと同期するアプリ。たとえば、SQLite データベース ファイルなどです。
- ワーカーまたは別のタブからメインスレッドにファイル システムの変更を通知する必要があるアプリ。
- リソースのディレクトリを監視するアプリ（画像を自動的に最適化するなど）。
- ファイル変更によってリロードがトリガーされる HTML ベースのスライドデッキなど、ホットリロードのメリットを活かせるエクスペリエンス。
File System Observer API の使用方法
特徴検出
FileSystemObserver API がサポートされているかどうかを確認するには、次の例のように機能テストを実行します。
if ('FileSystemObserver' in self) {
// The File System Observer API is supported.
}
ファイル システム オブザーバーを初期化する
new FileSystemObserver() を呼び出し、引数として callback 関数を指定して、ファイル システム オブザーバーを初期化します。
const observer = new FileSystemObserver(callback);
ファイルまたはディレクトリの監視を開始する
ファイルまたはディレクトリの監視を開始するには、FileSystemObserver インスタンスの非同期 observe() メソッドを呼び出します。このメソッドには、選択したファイルまたはディレクトリの FileSystemHandle を引数として渡します。ディレクトリを監視する場合、ディレクトリの変更を再帰的に（つまり、ディレクトリ自体と、含まれるすべてのサブディレクトリとファイルに対して）通知するかどうかを選択できる options 引数があります。デフォルトのオプションでは、ディレクトリ自体と直接含まれるファイルのみが監視されます。
// Observe a file.
await observer.observe(fileHandle);
// Observe a directory.
await observer.observe(directoryHandle);
// Observe a directory recursively.
await observer.observe(directoryHandle, {recursive: true});
コールバック関数
ファイル システムに変更が発生すると、ファイル システムの変更 records と observer 自体を引数としてコールバック関数が呼び出されます。observer 引数を使用すると、たとえば、対象のファイルがすべて削除されたときにオブザーバーを切断できます（ファイル システムの監視を停止するを参照）。
const callback = (records, observer) => {
for (const record of records) {
console.log('Change detected', record);
}
};
ファイル システムの変更レコード
各ファイル システム変更レコードの構造は次のとおりです。すべてのフィールドは読み取り専用です。
root（FileSystemHandle）:FileSystemObserver.observe()関数に渡されるハンドル。changedHandle（FileSystemHandle）: ファイル システムの変更の影響を受けるハンドル。このフィールドは、"errored"、"unknown"、"disappeared"タイプのイベントではnullになります。どのファイルまたはディレクトリが消えたかを確認するには、relativePathComponentsを使用します。relativePathComponents（Array）:rootを基準としたchangedHandleのパス。type（String）: 変更のタイプ。次のタイプを使用できます。"appeared": ファイルまたはディレクトリが作成されたか、rootに移動されました。"disappeared": ファイルまたはディレクトリが削除されたか、rootから移動されました。"modified": ファイルまたはディレクトリが変更されました。"moved": ファイルまたはディレクトリがroot内で移動されました。"unknown": 0 個以上のイベントが欠落したことを示します。デベロッパーは、これに応じて監視対象のディレクトリをポーリングする必要があります。"errored": モニタリングが無効になりました。この場合は、ファイル システムの監視を停止することをおすすめします。この値は、オリジンごとの観測数の上限に達したときにも送信されます。この上限はオペレーティング システムによって異なり、事前に知ることはできません。この場合、サイトは再試行を決定する可能性がありますが、オペレーティング システムが十分なリソースを解放した保証はありません。この値が送信されるもう 1 つのケースは、観測されたハンドル（観測のルート）が削除または移動された場合です。この場合、まず"disappeared"イベントが送信され、次に"errored"イベントが送信されて、モニタリングが無効になったことが示されます。最後に、このイベントは、ディレクトリまたはファイル ハンドルの権限が削除されたときに送信されます。
relativePathMovedFrom（Array、省略可）: 移動したハンドルの以前の場所。typeが"moved"の場合にのみ使用できます。
ファイルまたはディレクトリの監視を停止する
FileSystemHandle の監視を停止するには、unobserve() メソッドを呼び出し、ハンドルを引数として渡します。
observer.unobserve(fileHandle);
ファイル システムの監視を停止する
ファイル システムの監視を停止するには、次のように FileSystemObserver インスタンスを切断します。
observer.disconnect();
API を試す
FileSystemObserver API をローカルでテストするには、about:flags で #file-system-observer フラグを設定します。実際のユーザーで API をテストするには、オリジン トライアルに登録し、ガイドの Chrome オリジン トライアルに沿って手順を進めます。オリジン トライアルは Chrome 129（2024 年 9 月 11 日）から Chrome 134（2025 年 2 月 26 日）まで実施されます。
デモ
埋め込みのデモで、File System Observer API の動作を確認できます。ソースコードを確認します。このデモでは、監視対象のディレクトリ内のファイルがランダムに作成、削除、変更され、そのアクティビティがアプリ ウィンドウの上部に記録されます。変更が発生すると、アプリ ウィンドウの下部に変更が記録されます。File System Observer API をサポートしていないブラウザでこのページをご覧になっている場合は、デモのスクリーンショットをご覧ください。
フィードバック
ファイル システム オブザーバー API の形状についてフィードバックがある場合は、WHATWG/fs の Issue #123 にコメントしてください。
関連リンク
謝辞
このドキュメントは、Daseul Lee、Nathan Memmott、Etienne Noël、Rachel Andrew によってレビューされました。