File System Access API と Origin Private File System API のどちらでも、デベロッパーはユーザーのデバイス上のファイルとディレクトリにアクセスできます。前者は、デベロッパーがユーザーに表示される通常のファイル システムに対して読み書きを行います。後者では、ユーザー ファイル システムから隠された特別なファイルを開くことができます。これは各サイトの origin に対して非公開であり、一定のパフォーマンス上の利点があります。いずれの場合も、デベロッパーがファイルやディレクトリを操作するには、FileSystemHandle オブジェクトを使用します。具体的には、ファイルの場合は FileSystemFileHandle、ディレクトリの場合は FileSystemDirectoryHandle です。これまでは、いずれかのファイル システム内のファイルやディレクトリに対する変更の通知を受けるには、なんらかの形でポーリングして lastModified タイムスタンプを比較するか、ファイルの内容自体を比較する必要がありました。
Chrome 129 のオリジン トライアルでの File System Observer API ではこの点が変更され、変更が発生した場合にデベロッパーに自動的にアラートを受け取ることができます。このガイドでは、この機能の仕組みと使用方法について説明します。
ユースケース
ファイル システムの変更が発生したらすぐに通知する必要があるアプリでは、File System Observer API を使用します。
- プロジェクトのファイル システム ツリーを表現するウェブベースの統合開発環境（IDE）。
- ファイル システムの変更をサーバーと同期させるアプリ。（例: SQLite データベース ファイル）。
- ワーカーや他のタブからファイル システムの変更をメインスレッドに通知する必要があるアプリ。
- たとえば、画像を自動的に最適化するために、リソースのディレクトリを監視するアプリ。
File System Observer API の使用方法
機能検出
File System Observer API がサポートされているかどうかを確認するには、次の例のように機能テストを実行します。
if ('FileSystemObserver' in self) {
// The File System Observer API is supported.
}
ファイル システム オブザーバーを初期化する
callback 関数を引数として指定し、new FileSystemObserver() を呼び出して File System Observer を初期化します。
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）: ファイル システムの変更の影響を受けるハンドル。relativePathComponents（Array）:rootに対するchangedHandleの相対パス。type（String）: 変更のタイプ。次の型があります。 <ph type="x-smartling-placeholder">- </ph>
"appeared": ファイルまたはディレクトリがrootに作成または移動されました。"disappeared":rootからファイルまたはディレクトリが削除されたか、移動されました。"modified": ファイルまたはディレクトリが変更されました。"moved":root内でファイルまたはディレクトリが移動されました。"unknown": 0 個以上のイベントが欠落したことを示します。デベロッパーは、これに応じて監視対象ディレクトリをポーリングする必要があります。"errored": 観測項目は無効になりました。この場合、ファイル システムの監視を停止することもできます。
relativePathMovedFrom（Array、省略可）: 移動されたハンドルの以前の場所。typeが"moved"の場合にのみ使用できます。
ファイルまたはディレクトリの監視を停止する
FileSystemHandle の監視を停止するには、unobserve() メソッドを呼び出して、ハンドルを引数として渡します。
observer.unobserve(fileHandle);
ファイル システムの監視を停止する
ファイル システムの監視を停止するには、次のように FileSystemObserver インスタンスの接続を解除します。
observer.disconnect();
API を試す
File System Observer API をローカルでテストするには、about:flags で #file-system-observer フラグを設定します。実際のユーザーで API をテストするには、オリジン トライアルに登録し、ガイドの Chrome オリジン トライアルの手順に沿って操作してください。オリジン トライアルは、Chrome 129（2024 年 9 月 11 日）から Chrome 134（2025 年 2 月 26 日）まで実施されます。
デモ
File System Observer API の実際の動作については、埋め込みのデモをご覧ください。ソースコードをチェックするか、デモコードを Glitch でリミックスしてください。このデモは、観察されたディレクトリ内でファイルをランダムに作成、削除、変更し、アプリのウィンドウの上部にそのアクティビティを記録します。次に、アプリ ウィンドウの下部に表示されるその変更をログに記録します。File System Observer API をサポートしていないブラウザでこれを確認するには、デモのスクリーンショットをご覧ください。
フィードバック
File System Observer API の形状についてフィードバックがある場合は、WHATWG/fs リポジトリの Issue #123 にコメントしてください。
関連リンク
謝辞
このドキュメントは、Daseul Lee、Nathan Memmott、Etienne Noël、Rachel Andrew がレビューしました。