File System Observer API 來源試用

File System Access APIOrigin 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});

回呼函式

檔案系統發生變更時,系統會使用檔案系統變更 recordsobserver 本身做為引數呼叫回呼函式。舉例來說,您可以使用 observer 引數,在您感興趣的檔案全部刪除時,中斷觀察器 (請參閱「停止觀察檔案系統」)。

const callback = (records, observer) => {
  for (const record of records) {
    console.log('Change detected', record);
  }
};

檔案系統變更記錄

每個檔案系統變更記錄都具有下列結構。所有欄位皆為唯讀欄位。

  • root (FileSystemHandle):傳遞至 FileSystemObserver.observe() 函式的句柄。
  • changedHandle (FileSystemHandle):受檔案系統變更影響的句柄。
  • relativePathComponents (Array):相對於 rootchangedHandle 路徑。
  • 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 存放區中的 Issue #123 提出意見。

特別銘謝

本文件由 Daseul LeeNathan MemmottEtienne NoëlRachel Andrew 審查。