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
(FileSystemHandle
):受檔案系統變更影響的句柄。relativePathComponents
(Array
):相對於root
的changedHandle
路徑。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 Lee、Nathan Memmott、Etienne Noël 和 Rachel Andrew 審查。