关于前端:源私有文件系统

文件系统规范（File System Standard）引入了源公有文件系统（origin private file system，OPFS），作为页面源公有的、用户不可见的存储端点，它提供了对一种非凡文件（a special kind of file）的可选拜访，并对性能进行了高度优化。

庆贺
源公有文件系统容许网络应用程序在本人特定的源虚构文件系统中存储和操作文件，包含低级文件操作、逐字节拜访和文件流。所有次要浏览器都反对源公有文件系统。

浏览器反对

源公有文件系统被古代浏览器反对，并由网络超文本应用程序技术工作组（WHATWG）标准化为 File System Living Standard。

动机

提到计算机上的文件，你可能会想到这样的文件层次结构：文件被组织在文件夹中——你能够用操作系统的文件资源管理器来查看。例如，在 Windows 上，对于一个名为 Tom 的用户，他的待办事项列表可能位于 C:\Users\Tom\Documents\ToDo.txt。在这个示例中，ToDo.txt 是文件名，Users、Tom 和 Documents 是文件夹名。Windows 上的 C:\ 示意驱动器的根目录。

在本文中，我交替应用 文件夹 和目录 这两个术语，而疏忽了文件系统概念（目录）和图形用户界面隐喻（文件夹）之间的区别。

在 Web 上解决文件的传统形式

若要在网络应用程序中编辑待办事项列表，这是传统的流程：

1. 用户将文件 上传 到服务器，或在客户端应用 <input type="file"> 关上 文件。
2. 用户进行编辑，而后通过 JavaScript 以编程形式对注入的 <a download="ToDo.txt"> 执行 click() 办法来 下载 生成的文件。
3. 要关上文件夹，能够应用 <input type="file" webkitdirectory>，只管该属性的名称具备公有前缀，但实际上失去了浏览器的广泛反对。

在 Web 上解决文件的古代形式

这种流程并不代表用户编辑文件的思维形式，这意味着用户最终只能下载其输出文件的 正本。因而，文件系统拜访 API（File System Access API）引入了三个选择器办法——showOpenFilePicker()、showSaveFilePicker() 和 showDirectoryPicker()，它们的性能和名称一样（译注：它们的性能顺次为关上文件、保留文件和关上目录）。通过它们，能够以如下的流程来解决文件：

1. 应用 showOpenFilePicker() 关上 ToDo.txt，失去一个 FileSystemFileHandle 对象。
2. 通过调用文件句柄 FileSystemFileHandle 对象的 getFile() 办法获取 File。
3. 编辑文件，而后在句柄上调用 requestPermission({mode: 'readwrite'})。
4. 如果用户承受权限申请，则将更改保留回原始文件。
5. 或者，调用 showSaveFilePicker() 让用户抉择一个新文件。（如果用户抉择的是之前关上的文件，其内容将被笼罩。）对于反复保留，能够保留文件句柄，这样就不用再次显示文件保留对话框。

在 Web 上解决文件的限度

通过这些办法拜访的文件和文件夹位于 用户可见 文件系统中。从网络上保留的文件，特地是可执行文件，都会被打上网络标记，因而在潜在危险文件被执行之前，操作系统会显示额定的正告。作为一项额定的平安性能，从网络上获取的文件也会受到平安浏览的爱护，为简略起见，在本文中，你能够将其视为基于云的病毒扫描。当应用文件系统拜访 API 向文件写入数据时，写入不是就地写入，而是会应用临时文件。除非通过所有这些安全检查，否则文件自身不会被批改。能够设想，即便在 macOS 等零碎上尽可能地进行了优化，但这些查看还是让文件操作变得绝对迟缓。尽管如此，每个 write() 调用都是独立的，因而它在后盾会关上文件，查找到给定的偏移量，并最终写入数据。

作为解决工作根底的文件

同时，文件也是记录数据的绝佳形式。例如，SQLite 将整个数据库存储在一个文件中。另一个例子是用于图像处理的 mipmaps。Mipmaps 是通过事后计算和优化的图像序列，每一幅图像都是前一幅图像的分辨率逐步升高的示意，这使得许多操作（如缩放）变得更快。那么，网络应用程序如何既能取得文件的劣势，又能防止传统网络文件解决的性能老本呢？答案是 源公有文件系统。

用户可见性与源公有文件系统

不同于通过操作系统的文件资源管理器浏览的、你能够读取、写入、挪动和重命名文件和文件夹的用户可见文件系统，源公有文件系统不会被用户看到。顾名思义，源公有文件系统中的文件和文件夹是公有的，更具体地说，是网站的源的公有文件系统。在 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 条目。如果你想要特地查看 fileSystem 条目标信息，请看 usageDetails 对象，它是按存储形式细分的。因为源公有文件系统对用户不可见，因而没有权限提醒，也没有平安浏览查看。

拜访根目录

要拜访根目录，请运行上面的命令。你最初会失去一个空目录句柄，更确切地说，是一个 FileSystemDirectoryHandle。

const opfsRoot = await navigator.storage.getDirectory();
// 类型为 "directory"、名称为 "" 的 FileSystemDirectoryHandle。console.log(opfsRoot);

主线程或 Web Worker

有两种办法应用源公有文件系统：在主线程上或在 Web Worker 中。Web Worker 不会阻塞主线程，这意味着在这里，API 能够是同步的，而在主线程上通常不会容许这种模式。同步 API 能够更快，因为它们能够防止解决 promise，且在 C 语言等能够编译成 WebAssembly 的语言中，文件操作通常是同步的。

// 这是同步的 C 代码。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()，它们都能解决 Blob 和 File。如果你违心，从 FileSystemFileHandle 获取 File 来“开释”数据，这样你就能够拜访它，并将其提供给用户可见文件系统。

const file = await fileHandle.getFile();
console.log(await file.text());

通过流写入文件

为了将数据流写入文件，你须要通过调用 createWritable() 创立一个 FileSystemWritableFileStream，而后应用 write() 将内容写入文件。最初，须要用 close() 来敞开流。

const contents = "Some text";
// 获取一个可写流。const writable = await fileHandle.createWritable();
// 将文件内容写入数据流。await writable.write(contents);
// 敞开数据流，保留内容。await writable.close();

删除文件和文件夹

通过调用特定文件或目录句柄上的 remove() 办法来删除文件和文件夹。要删除包含所有子文件夹在内的文件夹，请应用 {recursive: true} 选项。

await fileHandle.remove();
await directoryHandle.remove({recursive: true});

remove() 办法目前只在 Chrome 浏览器中实现。你能够通过 'remove' in FileSystemFileHandle.prototype 来检测浏览器是否反对该性能。

作为代替，如果晓得目录中要删除的文件或文件夹的名称，能够应用 removeEntry() 办法。

directoryHandle.removeEntry("my first nested file");

作为疾速提醒，await (await navigator.storage.getDirectory()).remove({recursive: true}) 是革除整个源公有文件系统的最快办法。

挪动和重命名文件和文件夹

应用 move() 办法重命名或挪动文件和文件夹。挪动和重命名能够同时进行，也能够独自进行。

// 重命名文件。await fileHandle.move("my first renamed file");
// 将文件挪动到另一个目录。await fileHandle.move(nestedDirectoryHandle);
// 将文件挪动到另一个目录并重命名。await fileHandle.move(
  nestedDirectoryHandle,
  "my first renamed and now nested file",
);

重命名和挪动文件夹在 Chrome 浏览器中尚未实现。你也不能将文件从源公有文件系统挪动到用户可见文件系统。不过你能够复制它们。

解析文件或文件夹的门路

要理解给定文件或文件夹绝对于参照目录（reference directory）的地位，请应用 resolve() 办法，并将 FileSystemHandle 作为参数传递给该办法。要获取源公有文件系统中文件或文件夹的残缺门路，请将通过 navigator.storage.getDirectory() 取得的根目录作为参照目录。

const relativePath = await opfsRoot.resolve(nestedDirectoryHandle);
// `relativePath` 为 `['my first folder', 'my first nested folder']`。

查看两个文件或文件夹句柄是否指向同一个文件或文件夹

有时，你有两个句柄，却不晓得它们是否指向同一个文件或文件夹。对于这种状况，能够应用 isSameEntry() 办法。

fileHandle.isSameEntry(nestedFileHandle);
// 返回 `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() 的 promise，而是间接推送 handle。

const getDirectoryEntriesRecursive = async (
  directoryHandle,
  relativePath = ".",
) => {const fileHandles = [];
  const directoryHandles = [];
  const entries = {};
  // 获取目录中文件和文件夹的迭代器。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，能够通过在一个惯例的 FileSystemFileHandle 上调用 createSyncAccessHandle() 获取。

const fileHandle = await opfsRoot.getFileHandle("my highspeed file.txt", {create: true,});
const syncAccessHandle = await fileHandle.createSyncAccessHandle();

这可能会令人困惑，但实际上，你能够从惯例的 FileSystemFileHandle 上取得 同步的 FileSystemSyncAccessHandle。还要留神的是，只管办法 createSyncAccessHandle() 的名称中蕴含 Sync，但该办法是 异步的。

同步就地文件办法

一旦领有了同步拜访句柄，你就能够拜访所有疾速的同步就地文件办法。

• 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();

// 依据文件大小初始化该变量。let size;
// 文件的以后大小，最后为 `0`。size = accessHandle.getSize();
// 编码要写入文件的内容。const content = textEncoder.encode("Some text");
// 将内容写入文件结尾。accessHandle.write(content, { at: size});
// 刷新（flush）更改。accessHandle.flush();
// 文件的以后大小，当初是 `9`（"Some text" 的长度）。size = accessHandle.getSize();

// 编码更多内容以写入文件。const moreContent = textEncoder.encode("More content");
// 将内容写入文件开端。accessHandle.write(moreContent, { at: size});
// 刷新（flush）更改。accessHandle.flush();
// 文件的以后大小，当初是 `21`（"Some textMore content" 的长度）。size = accessHandle.getSize();

// 筹备与文件具备雷同长度的 DataView。const dataView = new DataView(new ArrayBuffer(size));

// 将整个文件读入 DataView。accessHandle.read(dataView);
// 打印 `"Some textMore content"`。console.log(textDecoder.decode(dataView));

// 从偏移量 9 开始读入 DataView。accessHandle.read(dataView, { at: 9});
// 打印 `"More content"`。console.log(textDecoder.decode(dataView));

// 在 4 字节后截断文件。accessHandle.truncate(4);

请留神，read() 和 write() 的第一个参数是 ArrayBuffer 或 ArrayBufferView（如 DataView）。你不能间接操作 ArrayBuffer 中的内容。相同，你须要创立一个以特定格局示意缓冲区的类型化数组对象（如 Int8Array 或 DataView 对象），而后应用它来读写缓冲区中的内容。

从源公有文件系统向用户可见文件系统复制文件

如前所述，无奈将文件从源公有文件系统挪动到用户可见文件系统，但能够复制文件。因为 showSaveFilePicker() 只在主线程中裸露，而不存在于 Worker 线程中，所以请确保在主线程中运行上面的代码。

// 在主线程上，而不是在 Worker 中。// 假如 `fileHandle` 是你在 Worker 线程中用于获取的 `FileSystemSyncAccessHandle` 的 `FileSystemFileHandle`。// 请确保先敞开 Worker 线程中的文件。const fileHandle = await opfsRoot.getFileHandle("fast");
try {
  // 获取用户可见文件系统中新文件的句柄，该文件与源公有文件系统中的文件名雷同。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);
}

调试源公有文件系统

在内置的 DevTools 反对（参见 crbug/1284595）被增加之前，请应用 OPFS Explorer Chrome 浏览器扩大调试源公有文件系统。下面创立新文件和文件夹局部的截图就是间接从扩大中截取的。

装置扩大后，关上 Chrome 浏览器的 DevTools，抉择 OPFS Explorer 选项卡，而后你就能够查看文件层次结构了。点击文件名可将文件从源公有文件系统保留到用户可见文件系统，点击垃圾桶图标可删除文件或文件夹。

演示

在将源公有文件系统用作编译为 WebAssembly 的 SQLite 数据库后端的演示中，你能够看到源公有文件系统的运行状况（如果你装置了 OPFS Explorer 扩大）。请务必查看 Glitch 上的源代码。请留神，上面的嵌入式版本并不应用源公有文件系统后端（因为 iframe 是跨源的），但当你在独自的标签页中关上演示时，它就会应用。

（译注：这里嵌入不了 iframe，所以请点击 URL 查看演示：https://sqlite-wasm-opfs.glitch.me/）

论断

由 WHATWG 制订的源公有文件系统塑造了咱们在网络上应用文件和与文件交互的形式。它实现了用户可见文件系统无奈实现的新用例。所有次要的浏览器供应商——苹果、Mozilla 和谷歌——都参加其中，并领有独特的愿景。源公有文件系统的开发在很大水平上是一项合作工作，开发人员和用户的反馈对其停顿至关重要。在咱们不断完善和改良该规范的过程中，欢送以议题或拉取申请的形式向 whatwg/fs 存储库提供反馈。

相干链接

• 文件系统标准规范
• 文件系统规范仓库
• WebKit 博文 The File System API with Origin Private File System
• OPFS Explorer 扩大

致谢

本文由 Austin Sully、Etienne Noël 和 Rachel Andrew 审阅。封面图来自 Unsplash 上的 Christina Rumpf。