使用 browser-fs-access 库读取和写入文件和目录

Thomas Steiner

浏览器已经能够处理文件和目录很长时间了。File API 提供了用于在 Web 应用中表示文件对象的功能，以及以编程方式选择文件对象和访问其数据的功能。不过，仔细观察后，您会发现并非所有闪光的东西都是金子。

传统的文件处理方式

注意：如果您知道旧版的运作方式，可以直接跳到下文，了解新版的运作方式。

打开文件

作为开发者，您可以通过 <input type="file"> 元素打开和读取文件。打开文件的最简单形式类似于以下代码示例。input 对象为您提供了 FileList，在下面的示例中，它只包含一个 File。File 是特定类型的 Blob，可在 Blob 可以的任何上下文中使用。

const openFile = async () => {
  return new Promise((resolve) => {
    const input = document.createElement('input');
    input.type = 'file';
    input.addEventListener('change', () => {
      resolve(input.files[0]);
    });
    input.click();
  });
};

打开目录

如需打开文件夹（或目录），您可以设置 <input webkitdirectory> 属性。除此之外，所有其他方式均与上述方式相同。尽管 webkitdirectory 带有供应商前缀，但它不仅可在 Chromium 和 WebKit 浏览器中使用，还可在基于旧版 EdgeHTML 的 Edge 以及 Firefox 中使用。

保存（即下载）文件

传统上，如需保存文件，您只能下载文件，这得益于 <a download> 属性。对于给定的 Blob，您可以将锚点的 href 属性设置为可从 URL.createObjectURL() 方法获取的 blob: 网址。

注意：为防止内存泄露，请务必在下载后撤消网址。

const saveFile = async (blob) => {
  const a = document.createElement('a');
  a.download = 'my-file.txt';
  a.href = URL.createObjectURL(blob);
  a.addEventListener('click', (e) => {
    setTimeout(() => URL.revokeObjectURL(a.href), 30 * 1000);
  });
  a.click();
};

问题

“下载”方法的一个巨大缺点是，无法实现传统的“打开”→“修改”→“保存”流程，也就是说，无法覆盖原始文件。相反，每次您“保存”时，系统都会在操作系统的默认“下载内容”文件夹中创建原始文件的新副本。

File System Access API

File System Access API 可简化打开和保存这两项操作。 它还支持真正的保存，也就是说，您不仅可以选择文件的保存位置，还可以覆盖现有文件。

注意：如需更详细地了解 File System Access API，请参阅File System Access API：简化对本地文件的访问一文。

打开文件

使用 File System Access API 时，只需调用 window.showOpenFilePicker() 方法一次即可打开文件。此调用会返回一个文件句柄，您可以通过 getFile() 方法从该文件句柄中获取实际的 File。

const openFile = async () => {
  try {
    // Always returns an array.
    const [handle] = await window.showOpenFilePicker();
    return handle.getFile();
  } catch (err) {
    console.error(err.name, err.message);
  }
};

打开目录

通过调用 window.showDirectoryPicker() 打开目录，这样便可以在文件对话框中选择目录。

保存文件

保存文件同样简单。 您可以通过 createWritable() 从文件句柄创建可写入的流，然后调用流的 write() 方法写入 Blob 数据，最后调用其 close() 方法关闭流。

const saveFile = async (blob) => {
  try {
    const handle = await window.showSaveFilePicker({
      types: [{
        accept: {
          // Omitted
        },
      }],
    });
    const writable = await handle.createWritable();
    await writable.write(blob);
    await writable.close();
    return handle;
  } catch (err) {
    console.error(err.name, err.message);
  }
};

全新推出 browser-fs-access

虽然 File System Access API 非常出色，但尚未广泛提供。

File System Access API 的浏览器支持表。 （来源）

因此，我认为 File System Access API 是一项渐进式增强功能。因此，我想在浏览器支持时使用它，而不支持时使用传统方法；同时，绝不会让用户因下载不受支持的 JavaScript 代码而受到不必要的惩罚。browser-fs-access 库是我为解决此问题而提出的方案。

设计理念

由于 File System Access API 未来可能仍会发生变化，因此 browser-fs-access API 并未以其为蓝本。也就是说，该库不是 polyfill，而是 ponyfill。您可以（静态或动态）专门导入所需的任何功能，以尽可能减小应用的大小。可用的方法分别是名为 fileOpen()、directoryOpen() 和 fileSave() 的方法。在内部，该库会检测是否支持文件系统访问 API，然后导入相应的代码路径。

使用 browser-fs-access 库

这三种方法都非常直观易用。 您可以指定应用接受的 mimeTypes 或文件 extensions，并设置 multiple 标志以允许或禁止选择多个文件或目录。如需了解完整详情，请参阅 browser-fs-access API 文档。以下代码示例展示了如何打开和保存图片文件。

// The imported methods will use the File
// System Access API or a fallback implementation.
import {
  fileOpen,
  directoryOpen,
  fileSave,
} from 'https://unpkg.com/browser-fs-access';

(async () => {
  // Open an image file.
  const blob = await fileOpen({
    mimeTypes: ['image/*'],
  });

  // Open multiple image files.
  const blobs = await fileOpen({
    mimeTypes: ['image/*'],
    multiple: true,
  });

  // Open all files in a directory,
  // recursively including subdirectories.
  const blobsInDirectory = await directoryOpen({
    recursive: true
  });

  // Save a file.
  await fileSave(blob, {
    fileName: 'Untitled.png',
  });
})();

演示

您可以在 Glitch 上的演示中查看上述代码的实际运作情况。您也可以在该处找到其源代码。出于安全考虑，跨源子框架不允许显示文件选择器，因此无法将演示嵌入本文中。

实际使用的 browser-fs-access 库

在空闲时，我会为一款名为 Excalidraw 的可安装 PWA 贡献一点代码。Excalidraw 是一款白板工具，可让您以手绘的方式轻松绘制图表。它完全响应式，可在各种设备（从小屏手机到大屏幕计算机）上正常运行。 这意味着它需要处理各种不同平台上的文件，无论这些平台是否支持 File System Access API。这使得它非常适合 browser-fs-access 库。

例如，我可以在 iPhone 上开始绘制，将其保存（从技术层面讲，是下载，因为 Safari 不支持 File System Access API）到 iPhone 的“下载”文件夹，在桌面上打开该文件（从手机上传输后），修改该文件，并使用我所做的更改覆盖该文件，甚至可以将其另存为新文件。

在 iPhone 上启动 Excalidraw 绘图，该 iPhone 不支持 File System Access API，但可以将文件保存（下载）到“下载”文件夹。

在支持 File System Access API 且可通过该 API 访问文件的桌面设备上打开和修改 Excalidraw 绘图。

使用对原始 Excalidraw 绘图文件所做的修改覆盖原始文件。浏览器会显示一个对话框，询问我是否可以正常下载。

将修改内容保存到新的 Excalidraw 文件。原始文件将保持不变。

真实代码示例

下面，您可以看到 browser-fs-access 在 Excalidraw 中的实际使用示例。此摘录来自 /src/data/json.ts。特别值得注意的是，saveAsJSON() 方法如何将文件句柄或 null 传递给 browser-fs-access 的 fileSave() 方法，这会导致在提供句柄时覆盖，否则保存到新文件。

export const saveAsJSON = async (
  elements: readonly ExcalidrawElement[],
  appState: AppState,
  fileHandle: any,
) => {
  const serialized = serializeAsJSON(elements, appState);
  const blob = new Blob([serialized], {
    type: "application/json",
  });
  const name = `${appState.name}.excalidraw`;
  (window as any).handle = await fileSave(
    blob,
    {
      fileName: name,
      description: "Excalidraw file",
      extensions: ["excalidraw"],
    },
    fileHandle || null,
  );
};

export const loadFromJSON = async () => {
  const blob = await fileOpen({
    description: "Excalidraw files",
    extensions: ["json", "excalidraw"],
    mimeTypes: ["application/json"],
  });
  return loadFromBlob(blob);
};

界面注意事项

无论是在 Excalidraw 中还是在您的应用中，界面都应根据浏览器的支持情况进行调整。如果支持 File System Access API (if ('showOpenFilePicker' in window) {})，除了 Save 按钮之外，您还可以显示 Save As 按钮。以下屏幕截图显示了 Excalidraw 在 iPhone 和 Chrome 桌面设备上响应式主应用工具栏之间的差异。请注意，iPhone 上缺少另存为按钮。

iPhone 上的 Excalidraw 应用工具栏，仅包含一个 Save 按钮。

Chrome 上的 Exacalidraw 应用工具栏，其中显示了 Save 和处于聚焦状态的 Save As 按钮。

总结

从技术层面讲，在所有现代浏览器中都可以处理系统文件。在支持 File System Access API 的浏览器上，您可以允许真正保存和覆盖（而不仅仅是下载）文件，并允许用户在任何位置创建新文件，从而改善用户体验，同时在不支持 File System Access API 的浏览器上保持功能正常。browser-fs-access 可处理渐进增强的细微之处，并尽可能简化代码，让您的工作更轻松。

致谢

本文由 Joe Medley 和 Kayce Basques 审核。感谢 Excalidraw 的贡献者参与该项目的工作，并审核我的拉取请求。Ilya Pavlov 在 Un 创立平台上的主打图片。