前端文件系统访问 API：浏览器中的本地文件管理

文件系统访问 API（以前称为原生文件系统 API 或简称为文件系统 API）是一套强大的 Web API，它允许 Web 应用程序直接从浏览器与用户本地文件系统上的文件和目录进行交互。这为基于 Web 的应用程序开辟了新的可能性，使其能够执行以前仅限于原生应用程序的任务。

什么是文件系统访问 API？

文件系统访问 API 为用户提供了一种授予 Web 应用程序访问其本地文件系统权限的方式。与旧式的文件上传/下载机制不同，该 API 允许应用程序在获得用户明确同意后直接读取、写入和管理文件及目录。这提供了更加无缝和集成的体验，特别是对于处理大量本地数据或需要持久化存储的应用程序。

文件系统访问 API 的主要特点包括：

• 用户授权： 只有在用户明确批准请求后，才会授予对文件系统的访问权限，确保用户隐私和安全。
• 持久化存储： Web 应用程序可以请求持久化存储，允许它们在浏览器关闭或刷新后仍能保留对文件和目录的访问权限。
• 异步操作： 该 API 主要使用异步操作，防止在文件系统交互期间 UI 冻结。
• 基于流的访问： 支持流式处理，可以高效地处理大文件，而无需将整个文件加载到内存中。
• 目录访问： 应用程序可以请求访问整个目录，从而能够管理多个文件和文件夹。
• 源私有文件系统 (OPFS)： 一个特殊的隔离文件系统部分，对网站源是唯一的，为特定用例提供了增强的性能和安全性。

文件系统访问 API 的用例

文件系统访问 API 为 Web 应用程序解锁了广泛的可能性。以下是一些常见的用例：

1. 本地文件编辑器和 IDE

基于 Web 的代码编辑器、文本编辑器和 IDE 可以利用该 API 直接打开、编辑和保存在用户本地文件系统上的文件。与传统的文件上传/下载工作流程相比，这提供了更接近原生的体验。想象一下，一个像 VS Code 这样的 Web IDE 可以直接编辑您本地存储的项目文件。

2. 图像和视频编辑工具

图像和视频编辑应用程序可以使用该 API 高效地处理存储在用户设备上的大型媒体文件。基于流的访问允许在不将整个内容加载到内存的情况下编辑文件，从而提高了性能并减少了内存消耗。例如，一个在线照片编辑器可以直接从您的计算机打开和保存图像，无需上传。

3. 文档管理系统

基于 Web 的文档管理系统可以与用户的本地文件系统无缝集成，允许他们直接从浏览器轻松访问、组织和管理他们的文档。想象一下，一个云存储服务允许您直接在其 Web 界面中打开和编辑本地文档。

4. 游戏开发

游戏开发者可以使用该 API 来存储游戏资源、保存游戏进度，并直接从用户的文件系统加载自定义内容。这使得在 Web 上可以实现更丰富、更具沉浸感的游戏体验。想象一下，一个基于 Web 的游戏可以将您的进度直接保存到您的计算机上。

5. 离线应用

文件系统访问 API 与服务工作线程 (service workers) 等其他技术相结合，可以创建功能强大的离线 Web 应用程序，即使用户未连接到互联网也能继续运行。数据可以使用该 API 存储在本地，并在恢复连接时与远程服务器同步。这对于需要在在线和离线环境中无缝工作的生产力应用尤其有用。例如，一个笔记应用可能会将笔记存储在本地，并在有网络连接时同步到云端。

6. 数据处理与分析

Web 应用程序可以利用该 API 来处理和分析本地存储的大型数据集。这对于科学研究、数据分析以及其他需要处理大量数据的应用特别有用。想象一下，一个基于 Web 的数据可视化工具可以直接处理您硬盘上的 CSV 文件。

如何使用文件系统访问 API

文件系统访问 API 提供了几个用于与文件系统交互的函数。以下是如何使用一些关键功能的基本概述：

1. 请求文件系统访问权限

第一步是向用户请求访问文件系统的权限。这通常通过使用 showOpenFilePicker() 或 showSaveFilePicker() 方法来完成。

showOpenFilePicker()

showOpenFilePicker() 方法会提示用户选择一个或多个文件。它返回一个 promise，该 promise 会解析为一个包含 FileSystemFileHandle 对象的数组，这些对象代表了所选的文件。

            
async function openFile() {
  try {
    const [fileHandle] = await window.showOpenFilePicker();
    const file = await fileHandle.getFile();
    const contents = await file.text();
    console.log(contents);
  } catch (err) {
    console.error(err.name, err.message);
  }
}

            

              
                Copy
              
            
          

示例说明：

• `async function openFile() { ... }`: 定义一个异步函数来处理文件打开过程。
• `const [fileHandle] = await window.showOpenFilePicker();`: 使用 `showOpenFilePicker()` 显示一个文件选择对话框。`await` 关键字会暂停执行，直到用户选择一个文件（或取消操作）。结果是一个包含 `FileSystemFileHandle` 对象的数组；我们通过解构将第一个元素赋值给 `fileHandle` 变量。
• `const file = await fileHandle.getFile();`: 从 `FileSystemFileHandle` 中检索一个 `File` 对象。这个 `File` 对象提供了对文件属性和内容的访问。
• `const contents = await file.text();`: 使用 `text()` 方法将文件的全部内容读取为文本字符串。`await` 关键字等待文件读取操作完成。
• `console.log(contents);`: 将文件内容记录到控制台。
• `} catch (err) { ... }`: 捕获在文件打开或读取过程中可能发生的任何错误。它会将错误名称和消息记录到控制台以进行调试。这对于处理用户取消文件选择、文件无法访问或读取文件内容时出现问题等情况至关重要。

showSaveFilePicker()

showSaveFilePicker() 方法会提示用户选择一个位置来保存文件。它返回一个 promise，该 promise 会解析为一个 FileSystemFileHandle 对象，代表所选的文件。

            
async function saveFile(data) {
  try {
    const fileHandle = await window.showSaveFilePicker({
      suggestedName: 'my-file.txt',
      types: [{
        description: 'Text files',
        accept: {
          'text/plain': ['.txt'],
        },
      }],
    });
    const writable = await fileHandle.createWritable();
    await writable.write(data);
    await writable.close();
  } catch (err) {
    console.error(err.name, err.message);
  }
}

            

              
                Copy
              
            
          

示例说明：

• `async function saveFile(data) { ... }`: 定义一个异步函数 `saveFile`，它接受 `data`（要保存的内容）作为参数。
• `const fileHandle = await window.showSaveFilePicker({ ... });`: 调用 `showSaveFilePicker()` 来显示一个保存对话框。`await` 关键字确保函数等待用户的交互。 * `suggestedName: 'my-file.txt'` 建议一个默认文件名。 * `types: [...]` 指定文件类型过滤器： * `description: 'Text files'` 为文件类型提供一个用户友好的描述。 * `accept: { 'text/plain': ['.txt'] }` 表示对话框应筛选 MIME 类型为 `text/plain` 的 `.txt` 文件。
• `const writable = await fileHandle.createWritable();`: 创建一个与文件句柄关联的 `FileSystemWritableFileStream`。这个流允许向文件写入数据。
• `await writable.write(data);`: 将 `data`（要保存的内容）写入可写流。
• `await writable.close();`: 关闭可写流，确保所有数据都已写入文件并且文件已正确最终化。
• `} catch (err) { ... }`: 包含错误处理，以捕获并记录在保存过程中可能发生的任何错误。

2. 读取文件内容

一旦你拥有一个 FileSystemFileHandle 对象，你就可以使用 getFile() 方法来访问文件的内容。该方法返回一个 File 对象，它提供了将文件内容读取为文本、二进制数据或流的方法。

            
async function readFileContents(fileHandle) {
  const file = await fileHandle.getFile();
  const contents = await file.text();
  return contents;
}

            

              
                Copy
              
            
          

3. 写入文件

要写入文件，你需要使用 FileSystemFileHandle 对象的 createWritable() 方法创建一个 FileSystemWritableFileStream 对象。然后，你可以使用 write() 方法将数据写入流，并使用 close() 方法关闭流并保存更改。

            
async function writeFileContents(fileHandle, data) {
  const writable = await fileHandle.createWritable();
  await writable.write(data);
  await writable.close();
}

            

              
                Copy
              
            
          

4. 访问目录

文件系统访问 API 也允许你请求访问目录。这可以通过使用 showDirectoryPicker() 方法来完成。

            
async function openDirectory() {
  try {
    const directoryHandle = await window.showDirectoryPicker();
    console.log('directoryHandle', directoryHandle);
    // Now you can interact with the directoryHandle to list files, create new files, etc.
  } catch (err) {
    console.error(err.name, err.message);
  }
}

            

              
                Copy
              
            
          

一旦你拥有一个 FileSystemDirectoryHandle 对象，你就可以使用像 entries()、getFileHandle() 和 getDirectoryHandle() 这样的方法来导航目录结构并访问文件和子目录。

5. 源私有文件系统 (OPFS)

源私有文件系统 (OPFS) 是文件系统的一个特殊的、沙盒化的部分，它与 Web 应用程序的源隔离。访问 OPFS 中的文件针对性能进行了优化。以下是如何访问它：

            
async function accessOPFS() {
  try {
    const root = await navigator.storage.getDirectory();
    console.log('OPFS root directory handle:', root);

    // Create a file in the OPFS
    const fileHandle = await root.getFileHandle('my-opfs-file.txt', { create: true });
    const writable = await fileHandle.createWritable();
    await writable.write('This is data in the OPFS!');
    await writable.close();

    // Read the file back
    const file = await fileHandle.getFile();
    const contents = await file.text();
    console.log('Contents from OPFS file:', contents);
  } catch (err) {
    console.error('Error accessing OPFS:', err);
  }
}

accessOPFS();

            

              
                Copy
              
            
          

说明：

• `navigator.storage.getDirectory()`: 检索 OPFS 的根目录句柄。这是访问源私有文件系统中文件的入口点。
• `root.getFileHandle('my-opfs-file.txt', { create: true })`: 检索名为 'my-opfs-file.txt' 的文件的文件句柄。`{ create: true }` 选项确保如果文件尚不存在，则会创建它。
• 其余代码演示了如何向文件写入数据然后再次读回，与前面的示例类似。

安全注意事项

文件系统访问 API 引入了新的安全注意事项，开发者需要意识到：

• 用户权限： 始终只请求必要的权限，并向用户清楚地解释为什么你的应用程序需要访问他们的文件系统。
• 输入验证： 对从文件中读取的任何数据进行净化和验证，以防止跨站脚本 (XSS) 或代码注入等安全漏洞。
• 路径遍历： 在构造文件路径时要小心，以防止路径遍历攻击，攻击者可能会借此访问到预期目录之外的文件。
• 数据敏感性： 注意你正在处理的数据的敏感性，并采取适当的措施来保护它，例如加密和访问控制。
• 避免存储敏感数据： 如果可能，避免在用户的文件系统上存储敏感信息。考虑使用浏览器存储 API（如 IndexedDB）将数据存储在浏览器的沙盒中。

浏览器兼容性

浏览器对文件系统访问 API 的支持仍在不断发展中。虽然大多数现代浏览器都支持该 API 的核心功能，但某些功能可能仍处于实验阶段或需要启用特定标志。在生产环境中使用该 API 之前，请务必检查最新的浏览器兼容性信息。你可以参考 MDN Web Docs 等资源获取最新的兼容性详情。

Polyfills 和回退方案

对于不完全支持文件系统访问 API 的浏览器，你可以使用 polyfills 或回退方案来提供更优雅的降级。例如，对于不支持 showOpenFilePicker() 或 showSaveFilePicker() 方法的浏览器，你可以使用传统的文件上传/下载机制作为回退。同时也要考虑渐进增强你的应用程序。在没有该 API 的情况下提供核心功能，然后为支持它的浏览器增强体验。

示例：创建一个简单的文本编辑器

以下是如何使用文件系统访问 API 创建一个基本文本编辑器的简化示例：

            
<textarea id="editor" style="width: 100%; height: 300px;"></textarea>
<button id="openBtn">Open File</button>
<button id="saveBtn">Save File</button>

            

              
                Copy
              
            
          

            
const editor = document.getElementById('editor');
const openBtn = document.getElementById('openBtn');
const saveBtn = document.getElementById('saveBtn');

let fileHandle;

openBtn.addEventListener('click', async () => {
  try {
    [fileHandle] = await window.showOpenFilePicker();
    const file = await fileHandle.getFile();
    editor.value = await file.text();
  } catch (err) {
    console.error(err.name, err.message);
  }
});

saveBtn.addEventListener('click', async () => {
  try {
    if (!fileHandle) {
      fileHandle = await window.showSaveFilePicker();
    }
    const writable = await fileHandle.createWritable();
    await writable.write(editor.value);
    await writable.close();
  } catch (err) {
    console.error(err.name, err.message);
  }
});

            

              
                Copy
              
            
          

这个例子演示了如何打开一个文件，在文本区域显示其内容，并将更改保存回文件。这是一个非常基础的例子，对于一个真实世界的应用程序，还需要额外的错误处理和功能。

使用文件系统访问 API 的最佳实践

• 渐进增强： 设计你的应用程序，使其即使在没有文件系统访问 API 的情况下也能工作。当 API 可用时，用它来增强用户体验。
• 提供清晰的解释： 向用户清楚地解释为什么你的应用程序需要访问他们的文件系统，以及你打算如何处理这些文件。
• 优雅地处理错误： 实现健壮的错误处理，以优雅地处理用户拒绝权限、文件未找到或其他错误的情况。
• 使用异步操作： 始终使用异步操作，以防止在文件系统交互期间 UI 冻结。
• 优化性能： 对大文件使用基于流的访问，以提高性能并减少内存消耗。
• 尊重用户隐私： 注意用户隐私，只访问你的应用程序运行所必需的文件和目录。
• 彻底测试： 在不同的浏览器和操作系统中彻底测试你的应用程序，以确保兼容性和稳定性。
• 考虑源私有文件系统 (OPFS)： 对于性能关键的操作，特别是涉及大文件的操作，考虑使用 OPFS。

结论

文件系统访问 API 是一个强大的工具，它使前端开发者能够创建具有增强文件系统功能的 Web 应用程序。通过允许用户授予 Web 应用程序访问其本地文件和目录的权限，该 API 为基于 Web 的生产力工具、创意应用等开辟了新的可能性。虽然浏览器支持仍在发展中，但文件系统访问 API 代表了 Web 开发演进中的重要一步。随着浏览器支持的成熟和开发者对该 API 经验的增加，我们可以期待看到更多利用其功能的创新和引人注目的 Web 应用程序。

请记住，在使用文件系统访问 API 时，始终要优先考虑用户安全和隐私。通过遵循最佳实践并仔细考虑安全影响，你可以创建既强大又安全的 Web 应用程序。