開發人員可透過 File System Access API 和 Origin Private File System API 存取使用者裝置上的檔案和目錄。前者可讓開發人員讀取及寫入一般使用者可見的檔案系統，後者則會開啟使用者看不到的特殊檔案系統，這個檔案系統專屬於每個網站的來源，並具有特定效能優勢。在這兩種情況下，開發人員都是透過 FileSystemHandle 物件與檔案和目錄互動，具體來說，檔案是 FileSystemFileHandle，目錄則是 FileSystemDirectoryHandle。到目前為止，如要瞭解任一檔案系統中的檔案或目錄變更，都必須進行某種形式的輪詢，並比較 lastModified 時間戳記，甚至是檔案內容本身。
Chrome 129 版開始的來源試用計畫中，檔案系統觀察員 API 改變了這種情況，讓開發人員在發生變更時自動收到通知。本指南將說明這項功能的運作方式，以及如何試用。
用途
如果應用程式需要瞭解檔案系統可能發生的變更，請使用 File System Observer API。
- 以網頁為基礎的整合開發環境 (IDE)，可顯示專案檔案系統樹狀結構的表示法。
- 與伺服器同步處理檔案系統變更的應用程式。例如 SQLite 資料庫檔案。
- 應用程式需要從背景工作或另一個分頁標籤通知主執行緒檔案系統變更。
- 監控資源目錄的應用程式，例如自動最佳化圖片。
- 可從熱重載獲益的體驗，例如以 HTML 為基礎的投影片組，其中檔案變更會觸發重載。
如何使用 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 引數，決定是否要以遞迴方式接收目錄變更通知 (也就是目錄本身，以及所有包含的子目錄和檔案)。預設選項是只觀察目錄本身和直接包含的檔案。
// 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(aFileSystemHandle)：受檔案系統變更影響的控制代碼。如果是"errored"、"unknown"和"disappeared"類型的事件，這個欄位會是null。如要查看消失的檔案或目錄，請使用relativePathComponents。relativePathComponents(Array)：changedHandle相對於root的路徑。type(aString)：變更類型。可能的類型如下："appeared"：檔案或目錄已建立或移至root。"disappeared"：檔案或目錄已刪除，或移出root。"modified"：檔案或目錄已修改。"moved"：檔案或目錄已移至root內。"unknown"：表示錯過零或多個事件。開發人員應輪詢監看的目錄，以回應這項要求。"errored"：觀察結果已失效，在這種情況下，您可能需要停止觀察檔案系統。達到每個來源的觀察值上限時，系統也會傳送這個值。這項限制取決於作業系統，且無法事先得知。如果發生這種情況，網站可能會決定重試，但無法保證作業系統已釋出足夠資源。如果觀察到的控制代碼 (即觀察的根目錄) 遭到刪除或移動，系統也會傳送這個值。在本例中，系統會先傳送"disappeared"事件，再傳送"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 的實際運作情形。查看原始碼。這個範例會在受監控的目錄中隨機建立、刪除或修改檔案，並在應用程式視窗上方記錄活動。然後，應用程式視窗的下半部會記錄變更。如果您使用的瀏覽器不支援 File System Observer API，請參閱示範的螢幕截圖。
意見回饋
如要對 File System Observer API 的形狀提供意見，請在 WHATWG/fs 存放區中留言給問題 #123。
相關連結
特別銘謝
本文由 Daseul Lee、Nathan Memmott、Etienne Noël 和 Rachel Andrew 審查。