本頁面由 Cloud Translation API 翻譯而成。

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 資料庫檔案。
需要透過背景工作執行緒或其他分頁，向主執行緒通知檔案系統變更的應用程式。
例如觀察資源目錄的應用程式，可自動最佳化圖片。
可從熱載機制中獲益的體驗，例如以 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 (a 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" 時才能使用。

停止觀察檔案或目錄

如要停止觀察 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 審查。