File System Observer API 來源試用

Thomas Steiner

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.
}

注意： 請參閱說明，瞭解透過輪詢的方式，對 File System Observer API 行為進行聚集的一般方法。

初始化檔案系統觀察器

呼叫 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" 時才能使用。

，瞭解如何調查及移除這項存取權。

注意： 視作業系統而定，並非所有變更事件的詳細資料層級都相同，例如當目錄內容以遞迴方式變更時。盡量網站會收到詳細的變更記錄，內含變更類型和受影響路徑的控制代碼。更糟的是，網站會收到較籠統的變更記錄 (也就是值為 "unknown" 的 type)，但仍需要網站列舉目錄才能找出哪個子項有所變更。這仍是輪詢的改善空間，因為目錄列舉可由回呼函式隨需啟用，而不需要輪詢時間間隔內的變更。

注意： Windows "moved" 事件不支援目錄之間的變更。它們會從來源目錄回報為 "disappeared"，並在目的地目錄中回報為 "appeared"。如果來源和目的地位於相同目錄中，則會回報為 "moved"。

停止觀察檔案或目錄

如要停止觀察 FileSystemHandle，請呼叫 unobserve() 方法，將控制代碼做為引數傳遞。

observer.unobserve(fileHandle);

注意： 來源試用期間不支援 unobserve() 方法。請改用 disconnect() 方法。

停止觀察檔案系統

如要停止觀察檔案系統，請按照下列步驟中斷 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 提供意見。

相關連結

• 說明
• TAG 審查
• Mozilla 標準定位
• WebKit 標準排名
• ChromeStatus
• Chromium 錯誤

特別銘謝

這份文件已由 Daseul Lee、Nathan Memmott、Etienne Noël 和 Rachel Andrew 審查。