檔案系統標準引進了來源私人檔案系統 (OPFS),做為頁面來源的私人儲存空間端點,且對使用者隱藏,可選擇存取效能經過高度最佳化的特殊檔案。
瀏覽器支援
來源私人檔案系統受到新式瀏覽器的支援,並由 Web Hypertext Application Technology Working Group (WHATWG) 在檔案系統 Living Standard 中標準化。
動機
提到電腦上的檔案,你可能會想到檔案階層:檔案以資料夾分類,你可以透過作業系統的檔案總管瀏覽。舉例來說,在 Windows 上,如果使用者名為 Tom,其待辦事項清單可能會位於 C:\Users\Tom\Documents\ToDo.txt
。在此範例中,ToDo.txt
是檔案名稱,而 Users
、Tom
和 Documents
是資料夾名稱。Windows 上的 `C:` 代表磁碟機的根目錄。
在網路上處理檔案的傳統方法
如要編輯網頁應用程式中的待辦事項清單,通常會採用以下流程:
- 使用者可以使用
<input type="file">
在用戶端上上傳檔案,或開啟檔案。 - 使用者進行變更後,系統會下載產生的檔案,並透過您透過 JavaScript 以程式輔助方式
click()
插入的<a download="ToDo.txt>
。 - 開啟資料夾時,您可在
<input type="file" webkitdirectory>
中使用特殊屬性,儘管其專屬名稱雖然其專屬名稱卻幾乎適用於通用的瀏覽器。
在網路上使用檔案的現代化方式
這個流程並不代表使用者編輯檔案的想法,也就是說,使用者最終會下載輸入檔案的副本。因此,File System Access API 推出了三種選擇器方法:showOpenFilePicker()
、showSaveFilePicker()
和 showDirectoryPicker()
,這些方法的名稱與功能完全一致。這些功能可啟用以下流程:
- 使用
showOpenFilePicker()
開啟ToDo.txt
,並取得FileSystemFileHandle
物件。 - 從
FileSystemFileHandle
物件取得File
,方法是呼叫檔案控點的getFile()
方法。 - 修改檔案,然後在句柄上呼叫
requestPermission({mode: 'readwrite'})
。 - 如果使用者接受權限要求,請將變更儲存回原始檔案。
- 或者,您也可以呼叫
showSaveFilePicker()
,讓使用者選擇新的檔案。(如果使用者選取先前開啟的檔案,系統會覆寫該檔案的內容)。如要重複儲存,您可以保留檔案句柄,這樣就不必再次顯示檔案儲存對話方塊。
在網路上使用檔案的限制
可透過這些方法存取的檔案和資料夾,位於稱為「使用者可見」的檔案系統中。從網路儲存的檔案,尤其是可執行檔案,都會標示為網路標記,因此在執行可能有危險的檔案前,作業系統會顯示額外警告。做為額外安全性功能,從網路取得的檔案也會受到安全瀏覽的保護。安全瀏覽功能是為了簡單起見,因此您可以參考本文,視為雲端病毒掃描。使用 File System Access API 將資料寫入檔案時,寫入作業並非原地執行,而是使用暫存檔案。除非檔案通過所有安全性檢查,否則不會修改檔案本身。您可以想像,這項作業會讓檔案作業變得相對緩慢,即使在 macOS 上也一樣。不過,每個 write()
呼叫都是獨立的,因此在幕後會開啟檔案、尋找指定的偏移量,最後再寫入資料。
以檔案做為處理作業的基礎
同時,檔案也是記錄資料的絕佳方式。舉例來說,SQLite 會將整個資料庫儲存在單一檔案中。另一個範例是圖像處理中使用的mipmap。Mipmap 是預先計算的最佳化圖片序列,每個圖片都會以逐漸降低的解析度呈現,因此許多操作 (例如縮放) 的速度會變快。那麼,網頁應用程式要如何取得檔案的優點,卻不必付出以網頁為基礎的檔案處理效能成本呢?答案是原始私人檔案系統。
使用者可見的系統與來源私人檔案系統
與使用作業系統檔案總管瀏覽的使用者可見檔案系統不同,原始私人檔案系統並非供使用者查看,如名稱所示,來源私密檔案系統中的檔案和資料夾屬於私密性質,更具體來說,是屬於網站的來源。在 DevTools 主控台中輸入 location.origin
,即可查看網頁的來源。舉例來說,頁面 https://developer.chrome.com/articles/
的來源是 https://developer.chrome.com
(也就是說,/articles
部分「不是」來源的一部分)。如要進一步瞭解來源理論,請參閱「瞭解『相同網站』和『相同來源』」一文。所有共用相同來源的網頁都可以查看相同來源的私人檔案系統資料,因此 https://developer.chrome.com/docs/extensions/mv3/getstarted/extensions-101/
可以查看與先前範例相同的詳細資料。每個來源都有各自的獨立來源私人檔案系統,也就是說,https://developer.chrome.com
的來源私人檔案系統與 https://web.dev
的來源私人檔案系統完全不同。在 Windows 上,使用者可見檔案系統的根目錄為 C:\\
。原始私人檔案系統的同等項目是每個來源的初始空白根目錄,其可透過呼叫非同步方法 navigator.storage.getDirectory()
存取。如需使用者可見的檔案系統與來源私人檔案系統的比較,請參閱下方圖表。這張圖表顯示除了根目錄以外,其他所有項目的概念都相同,即依照資料和儲存空間需求,採用階層式檔案和資料夾階層來整理和排列。
來源私人檔案系統注意事項
與瀏覽器中的其他儲存機制 (例如 localStorage 或 IndexedDB) 一樣,原始私人檔案系統會受到瀏覽器配額限制。當使用者清除所有瀏覽資料或所有網站資料時,也會刪除原始私人檔案系統。請呼叫 navigator.storage.estimate()
,並在產生的回應物件中查看 usage
項目,瞭解應用程式已使用的儲存空間量,這些資料會依 usageDetails
物件中的儲存空間機制細分,您可以查看 fileSystem
項目。由於使用者無法查看來源私人檔案系統,因此不會顯示權限提示,也不會進行安全瀏覽檢查。
取得根目錄的存取權
如要取得根目錄的存取權,請執行下列指令。最終會產生空白的目錄控點,更具體來說,也就是 FileSystemDirectoryHandle
。
const opfsRoot = await navigator.storage.getDirectory();
// A FileSystemDirectoryHandle whose type is "directory"
// and whose name is "".
console.log(opfsRoot);
主執行緒或網路工作站
使用來源私人檔案系統的方式有兩種:在主執行緒或Web Worker 中。Web Workers 無法封鎖主執行緒,這表示在這個情況下 API 可以是同步的,而這類模式通常不允許在主執行緒上執行。同步 API 的速度不會因為不處理承諾而加快,而且檔案作業通常會同步在可編譯至 WebAssembly 的 C 等語言中。
// This is synchronous C code.
FILE *f;
f = fopen("example.txt", "w+");
fputs("Some text\n", f);
fclose(f);
如果您需要盡可能快速的檔案作業,或是要處理 WebAssembly,請直接跳到「在 Web Worker 中使用原始私人檔案系統」一節。否則,請繼續閱讀。
在主執行緒上使用來源私人檔案系統
建立新的檔案和資料夾
建立根資料夾後,請分別使用 getFileHandle()
和 getDirectoryHandle()
方法建立檔案和資料夾。傳遞 {create: true}
後,如果檔案或資料夾不存在,系統就會建立。使用新建立的目錄做為起點來呼叫這些函式,藉此建立檔案階層。
const fileHandle = await opfsRoot
.getFileHandle('my first file', {create: true});
const directoryHandle = await opfsRoot
.getDirectoryHandle('my first folder', {create: true});
const nestedFileHandle = await directoryHandle
.getFileHandle('my first nested file', {create: true});
const nestedDirectoryHandle = await directoryHandle
.getDirectoryHandle('my first nested folder', {create: true});
存取現有的檔案和資料夾
如果您知道檔案或資料夾的名稱,請呼叫 getFileHandle()
或 getDirectoryHandle()
方法,並傳入檔案或資料夾名稱,即可存取先前建立的檔案和資料夾。
const existingFileHandle = await opfsRoot.getFileHandle('my first file');
const existingDirectoryHandle = await opfsRoot
.getDirectoryHandle('my first folder');
取得與檔案句柄相關聯的檔案以供讀取
FileSystemFileHandle
代表檔案系統中的檔案。如要取得相關聯的 File
,請使用 getFile()
方法。File
物件是特定類型的 Blob
,可用於 Blob
可用的任何情境。具體來說,FileReader
、URL.createObjectURL()
、createImageBitmap()
和 XMLHttpRequest.send()
都接受 Blobs
和 Files
。如果您找到的話,從 FileSystemFileHandle
取得 File
會「釋出」資料,以便您存取該資料並將資料提供給使用者可見的檔案系統。
const file = await fileHandle.getFile();
console.log(await file.text());
透過串流寫入檔案
請呼叫 createWritable()
將資料串流至檔案,這會建立 FileSystemWritableFileStream
,然後您可以write()
內容。最後,您需要close()
串流。
const contents = 'Some text';
// Get a writable stream.
const writable = await fileHandle.createWritable();
// Write the contents of the file to the stream.
await writable.write(contents);
// Close the stream, which persists the contents.
await writable.close();
刪除檔案和資料夾
呼叫這些檔案或目錄控制代碼的特定 remove()
方法,即可刪除檔案和資料夾。如要刪除資料夾及其所有子資料夾,請傳遞 {recursive: true}
選項。
await fileHandle.remove();
await directoryHandle.remove({recursive: true});
或者,如果您知道要刪除目錄中要刪除檔案或資料夾的名稱,請使用 removeEntry()
方法。
directoryHandle.removeEntry('my first nested file');
移動及重新命名檔案和資料夾
使用 move()
方法重新命名及移動檔案和資料夾。你可以同時移動及重新命名,也可以分開進行。
// Rename a file.
await fileHandle.move('my first renamed file');
// Move a file to another directory.
await fileHandle.move(nestedDirectoryHandle);
// Move a file to another directory and rename it.
await fileHandle
.move(nestedDirectoryHandle, 'my first renamed and now nested file');
解析檔案或資料夾的路徑
如要瞭解特定檔案或資料夾相對於參考目錄的位置,請使用 resolve()
方法,並將 FileSystemHandle
做為引數傳遞。如要取得來源私人檔案系統中檔案或資料夾的完整路徑,請使用根目錄做為透過 navigator.storage.getDirectory()
取得的參考目錄。
const relativePath = await opfsRoot.resolve(nestedDirectoryHandle);
// `relativePath` is `['my first folder', 'my first nested folder']`.
檢查兩個檔案或資料夾句柄是否指向相同的檔案或資料夾
有時您可能有兩個句柄,但不知道它們是否指向相同的檔案或資料夾。如要確認是否發生這種情況,請使用 isSameEntry()
方法。
fileHandle.isSameEntry(nestedFileHandle);
// Returns `false`.
列出資料夾的內容
FileSystemDirectoryHandle
是非同步疊代器,您可以透過 for await…of
迴圈對其進行疊代。做為非同步疊代器,也支援 entries()
、values()
和 keys()
方法,您可以根據需要的資訊選擇:
for await (let [name, handle] of directoryHandle) {}
for await (let [name, handle] of directoryHandle.entries()) {}
for await (let handle of directoryHandle.values()) {}
for await (let name of directoryHandle.keys()) {}
以遞迴方式列出資料夾和所有子資料夾的內容
處理非同步迴圈和與遞迴配對的函式時,很容易出錯。您可以從下列函式著手,其中列出資料夾及其所有子資料夾的內容 (包括所有檔案及其大小)。如果您不需要檔案大小,可以透過 directoryEntryPromises.push
簡化函式,不推送 handle.getFile()
承諾,而是直接推送 handle
。
const getDirectoryEntriesRecursive = async (
directoryHandle,
relativePath = '.',
) => {
const fileHandles = [];
const directoryHandles = [];
const entries = {};
// Get an iterator of the files and folders in the directory.
const directoryIterator = directoryHandle.values();
const directoryEntryPromises = [];
for await (const handle of directoryIterator) {
const nestedPath = `${relativePath}/${handle.name}`;
if (handle.kind === 'file') {
fileHandles.push({ handle, nestedPath });
directoryEntryPromises.push(
handle.getFile().then((file) => {
return {
name: handle.name,
kind: handle.kind,
size: file.size,
type: file.type,
lastModified: file.lastModified,
relativePath: nestedPath,
handle
};
}),
);
} else if (handle.kind === 'directory') {
directoryHandles.push({ handle, nestedPath });
directoryEntryPromises.push(
(async () => {
return {
name: handle.name,
kind: handle.kind,
relativePath: nestedPath,
entries:
await getDirectoryEntriesRecursive(handle, nestedPath),
handle,
};
})(),
);
}
}
const directoryEntries = await Promise.all(directoryEntryPromises);
directoryEntries.forEach((directoryEntry) => {
entries[directoryEntry.name] = directoryEntry;
});
return entries;
};
在 Web Worker 中使用來源私人檔案系統
如前所述,Web Worker 無法封鎖主執行緒,所以在此情境同步方法中可以使用。
取得同步存取控制代碼
最快的檔案作業進入點是 FileSystemSyncAccessHandle
,您可以呼叫 createSyncAccessHandle()
來從一般 FileSystemFileHandle
取得 FileSystemSyncAccessHandle
。
const fileHandle = await opfsRoot
.getFileHandle('my highspeed file.txt', {create: true});
const syncAccessHandle = await fileHandle.createSyncAccessHandle();
同步原地檔案方法
取得同步存取句柄後,您就能存取快速的在原地檔案方法,這些方法全都是同步的。
getSize()
:傳回檔案大小,以位元組為單位。write()
:將緩衝區的內容寫入檔案 (可選在指定偏移處),並傳回已寫入的位元組數。檢查傳回的位元組數可讓呼叫端偵測並處理錯誤和部分寫入作業。read()
:將檔案內容讀入緩衝區中,可選擇在指定偏移處讀取。truncate()
:將檔案大小調整為指定大小。flush()
:確保檔案內容包含透過write()
完成的所有修改。close()
:關閉存取控點。
以下是使用上述所有方法的範例。
const opfsRoot = await navigator.storage.getDirectory();
const fileHandle = await opfsRoot.getFileHandle('fast', {create: true});
const accessHandle = await fileHandle.createSyncAccessHandle();
const textEncoder = new TextEncoder();
const textDecoder = new TextDecoder();
// Initialize this variable for the size of the file.
let size;
// The current size of the file, initially `0`.
size = accessHandle.getSize();
// Encode content to write to the file.
const content = textEncoder.encode('Some text');
// Write the content at the beginning of the file.
accessHandle.write(content, {at: size});
// Flush the changes.
accessHandle.flush();
// The current size of the file, now `9` (the length of "Some text").
size = accessHandle.getSize();
// Encode more content to write to the file.
const moreContent = textEncoder.encode('More content');
// Write the content at the end of the file.
accessHandle.write(moreContent, {at: size});
// Flush the changes.
accessHandle.flush();
// The current size of the file, now `21` (the length of
// "Some textMore content").
size = accessHandle.getSize();
// Prepare a data view of the length of the file.
const dataView = new DataView(new ArrayBuffer(size));
// Read the entire file into the data view.
accessHandle.read(dataView);
// Logs `"Some textMore content"`.
console.log(textDecoder.decode(dataView));
// Read starting at offset 9 into the data view.
accessHandle.read(dataView, {at: 9});
// Logs `"More content"`.
console.log(textDecoder.decode(dataView));
// Truncate the file after 4 bytes.
accessHandle.truncate(4);
將檔案從來源私人檔案系統複製到使用者可見的檔案系統
如上所述,您無法將檔案從原始私人檔案系統移至使用者可見的檔案系統,但可以複製檔案。由於 showSaveFilePicker()
只會在主執行緒中公開,不會在 Worker 執行緒中公開,因此請務必在該處執行程式碼。
// On the main thread, not in the Worker. This assumes
// `fileHandle` is the `FileSystemFileHandle` you obtained
// the `FileSystemSyncAccessHandle` from in the Worker
// thread. Be sure to close the file in the Worker thread first.
const fileHandle = await opfsRoot.getFileHandle('fast');
try {
// Obtain a file handle to a new file in the user-visible file system
// with the same name as the file in the origin private file system.
const saveHandle = await showSaveFilePicker({
suggestedName: fileHandle.name || ''
});
const writable = await saveHandle.createWritable();
await writable.write(await fileHandle.getFile());
await writable.close();
} catch (err) {
console.error(err.name, err.message);
}
對原始私人檔案系統進行偵錯
在內建開發人員工具支援功能加入前 (請參閱 crbug/1284595),請使用 OPFS Explorer Chrome 擴充功能來偵錯原始私人檔案系統。順帶一提,上方「建立新檔案和資料夾」部分的螢幕截圖是直接從擴充功能擷取。
安裝擴充功能後,請開啟 Chrome 開發人員工具,然後選取「OPFS Explorer」分頁,即可檢查檔案階層。按一下檔案名稱,然後按一下垃圾桶圖示刪除檔案和資料夾,即可將來源私人檔案系統中的檔案儲存至使用者可檢視的檔案系統。
示範
在示範中,查看來源私人檔案系統的實際操作情形 (如果您安裝 OPFS Explorer 擴充功能),可將該系統做為編譯為 WebAssembly 的 SQLite 資料庫後端。請務必查看 Glitch 上的原始碼。請注意,下方的嵌入版本不會使用來源私人檔案系統後端 (因為 iframe 是跨來源),但在您在個別分頁中開啟示範時,就會使用來源私人檔案系統後端。
結論
根據 WHATWG 指定的來源私人檔案系統,我們決定了在網路上使用及與檔案互動的方式。這項功能可實現使用者無法透過可見檔案系統達成的新用途。所有主要瀏覽器供應商 (Apple、Mozilla 和 Google) 都加入了這個計畫,並分享共同願景。開發原始私人檔案系統需要多方合作,開發人員和使用者的意見回饋對其進展至關重要。在我們持續修正及改善標準的同時,歡迎您透過「問題」或「提取要求」形式對 whatwg/fs 存放區提供意見。
相關連結
特別銘謝
本文評論者為 Austin Sully、Etienne Noël 和 Rachel Andrew。主頁橫幅圖片由 Christina Rumpf 提供,取自 Unsplash。