File System Observer API 來源試用

Thomas Steiner

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 資料庫檔案。
• 需要從 worker 或其他分頁通知主執行緒檔案系統變更的應用程式。
• 例如觀察資源目錄的應用程式，可自動最佳化圖片。
• 可從熱載機制中獲益的體驗，例如以 HTML 為基礎的簡報資料，當檔案變更時會觸發重新載入。

如何使用 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 引數，選擇是否要以遞迴方式接收目錄變更通知 (也就是目錄本身和所有包含的子目錄和檔案)。預設選項是只觀察目錄本身和直接包含的檔案。

// 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)：changedHandle 相對於 root 的路徑。
• type (a String)：變更類型。可能的類型如下：
  • "appeared"：檔案或目錄已建立或移至 root。
  • "disappeared"：檔案或目錄已刪除或移出 root。
  • "modified"：檔案或目錄已修改。
  • "moved"：檔案或目錄已在 root 中移動。
  • "unknown"：這表示錯過零個或更多事件。開發人員應針對此情況輪詢已觀看目錄。
  • "errored"：觀察結果已失效。在這種情況下，您可能需要停止觀察檔案系統。當達到每個來源觀察值的最高限制時，系統也會傳送這個值。這項限制取決於作業系統，無法事先得知。發生這種情況時，網站可能會決定重試，但無法保證作業系統已釋出足夠的資源。另一種會傳送此值的情況是，當觀察到的句柄 (也就是觀察的根目錄) 遭到刪除或移動時。在這種情況下，系統會先傳送 "disappeared" 事件，接著傳送 "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 存放區中的 Issue #123 提出意見。

相關連結

• 說明
• TAG 審查
• Mozilla 標準立場
• WebKit 標準位置
• ChromeStatus
• Chromium 錯誤

特別銘謝

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