File System Access API 和 Origin Private File System API 可讓開發人員存取使用者裝置上的檔案和目錄。前者可讓開發人員讀取及寫入一般使用者可查看的檔案系統，而後者會開啟一個特殊檔案，隱藏在使用者檔案系統中，這是每個網站的來源專屬位置，在效能方面也有所提升。在這兩種情況下，開發人員與檔案和目錄的互動方式包括透過 FileSystemHandle 物件、更具體的說法、適用於檔案的 FileSystemFileHandle、FileSystemDirectoryHandle 用於目錄。截至目前為止，如要收到檔案系統中檔案或目錄的變更通知，您需要透過某些形式輪詢與比較 lastModified 時間戳記，甚至是檔案內容本身。
File System Observer API 是 Chrome 129 來源試用中的一項功能。這個 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.
}
初始化檔案系統觀察器
呼叫 new FileSystemObserver() 並提供 callback 函式做為引數，藉此初始化檔案系統觀察器。
const observer = new FileSystemObserver(callback);
開始觀察檔案或目錄
如要開始觀察檔案或目錄，請呼叫 FileSystemObserver 例項的非同步 observe() 方法。請將這個方法的 FileSystemHandle 做為引數提供所選檔案或目錄。觀察目錄時，我們提供了選用的 options 引數，可讓您選擇是否接收目錄異動通知 (也就是針對目錄本身和「all」包含子目錄和檔案)。預設選項僅觀察目錄本身以及直接包含的檔案。
// 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)：變更的類型。可能的類型如下："appeared"：檔案或目錄已建立或移至root。"disappeared"：檔案或目錄已遭刪除，或是已從root移出。"modified"：檔案或目錄經過修改。"moved"：檔案或目錄已在root中移動。"unknown"：表示錯過了零個或更多活動。開發人員應對此進行輪詢，並對觀察的目錄進行輪詢。"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 存放區的問題 #123 提供意見。
相關連結
特別銘謝
這份文件已由 Daseul Lee、Nathan Memmott、Etienne Noël 和 Rachel Andrew 審查。