File System Access API：Web 应用与本地文件系统交互的新桥梁

SeanTao
81 阅读6分钟

File System Access API：Web 应用与本地文件系统交互的新桥梁

今天分享一个文件系统相关的试验性API。

1. 什么是 File System Access API？

File System Access API 是一组现代 Web API，它允许 Web 应用在获得用户明确授权后，安全地读取、写入和管理用户本地设备上的文件和目录。传统 Web 文件处理方式（如 <input type="file">）只能让应用获得文件的临时快照，无法直接修改原始文件或获取其持久引用。而 File System Access API 引入了“文件句柄”的概念，提供了对实际文件的持久引用，从而实现了真正的文件读写能力。

2. 核心概念与工作原理

文件句柄（FileSystemFileHandle）与目录句柄（FileSystemDirectoryHandle）

文件句柄是 File System Access API 的核心抽象，它代表了文件系统中的一个文件的引用或“指针”，而不是文件内容本身。句柄是轻量级的且可序列化，可以被长期保存，实现持久化访问。同样，目录句柄允许对目录进行访问和操作，可以遍历、创建和删除文件及子目录。

安全上下文与用户手势

由于该 API 的强大能力，浏览器实施了严格的安全措施。所有能够触发文件或目录选择器的 API 调用都必须在安全上下文（HTTPS） 中执行，并且必须由用户的主动交互（如点击按钮） 触发。这意味着网页无法在后台静默地访问用户文件，用户始终掌握着控制权。

源私有文件系统（Origin Private File System, OPFS）

File System Access API 能够与两种文件系统交互：用户可见的常规文件系统和源私有文件系统（OPFS）。OPFS 是一个为每个网站源独立提供的、与操作系统文件系统隔离的沙箱化存储空间，它对用户不可见，但为 Web 应用提供了一个高性能的文件存储后端，特别适合需要频繁、快速读写的场景。

3. 主要功能与方法

文件选择与读取

使用 window.showOpenFilePicker()方法可以打开文件选择器，让用户选择一个或多个文件：

let fileHandle;
document.getElementById('openBtn').addEventListener('click', async () => {
  try {
    [fileHandle] = await window.showOpenFilePicker();
    const file = await fileHandle.getFile();
    const contents = await file.text();
    // 处理文件内容
  } catch (err) {
    if (err.name !== 'AbortError') {
      console.error('读取文件时出错:', err);
    }
  }
});

文件保存与写入

使用 window.showSaveFilePicker()可以保存文件，实现真正的“保存”而非“下载”：

async function saveFile(contents) {
  try {
    const fileHandle = await window.showSaveFilePicker({
      suggestedName: 'example.txt',
      types: [{
        description: 'Text Files',
        accept: {'text/plain': ['.txt']}
      }]
    });
    
    const writable = await fileHandle.createWritable();
    await writable.write(contents);
    await writable.close();
    console.log('文件保存成功');
  } catch (err) {
    console.error('保存文件时出错:', err);
  }
}

目录访问与操作

通过 window.showDirectoryPicker()可以访问整个目录结构：

document.getElementById('dirBtn').addEventListener('click', async () => {
  try {
    const directoryHandle = await window.showDirectoryPicker();
    for await (const entry of directoryHandle.values()) {
      console.log(entry.kind, entry.name);
    }
  } catch (err) {
    console.error('访问目录时出错:', err);
  }
});

4. 与传统方法的比较

下表清晰展示了 File System Access API 与传统方法的差异：

功能传统方法(<input>, <a download>)File System Access API
读取文件用户选择文件，应用获得临时内存副本用户选择文件，应用获得持久文件句柄
保存文件只能下载新副本，无法覆盖原始文件能够覆盖原始文件，实现真正"保存"
目录访问功能有限，依赖非标准属性提供标准 API，可遍历、创建和删除
用户体验"上传/下载"模式，页面刷新后状态丢失"打开/保存"模式，状态可持久化
权限模型隐式授予单次读取权限显式的、粒度化的读/写权限控制

5. 优势与应用场景

主要优势

  1. 真正的文件编辑能力：可以直接修改原始文件，而非创建新副本

  2. 持久化访问：文件句柄可以序列化并保存，实现长期访问

  3. 桌面级体验：提供类似原生应用的"打开/保存"工作流程

  4. 用户控制：所有操作都需要用户明确授权，确保安全性

典型应用场景

  • 文本编辑器与 IDE：实现 Web 版的 VS Code 等开发工具

  • 多媒体编辑器：图像、视频、音频编辑应用

  • 文件管理工具：Web 端的文件管理器

  • 数据导入/导出：高效处理大型数据文件

6. 安全考虑与限制

File System Access API 在设计时充分考虑了安全性：

  1. 用户授权：每个文件或目录访问都需要明确的用户授权

  2. 用户手势要求：文件选择器必须由用户交互触发

  3. 同源策略：API 遵循标准同源策略

  4. HTTPS 要求：必须在安全上下文中使用

权限模型方面，用户可以为每个文件或目录单独授予读取或读写权限，并且可以随时撤销这些权限。

7. 浏览器兼容性现状

目前，主要浏览器对 File System Access API 的支持情况如下：

  • Chrome/Edge：完全支持（Chrome 86+、Edge 86+）

  • Firefox：明确表示不会实现此 API，主要出于安全考虑

  • Safari：部分支持，但实现方式可能有所不同

  • Brave：基于 Chromium，但默认可能禁用此功能

由于兼容性限制，在实际项目中通常需要提供回退方案，如使用 IndexedDB 或 LocalStorage 作为不支持浏览器的替代方案。

8. 实际应用示例：简单文本编辑器

以下是一个基于 File System Access API 的简单文本编辑器核心代码：

class SimpleTextEditor {
  constructor() {
    this.fileHandle = null;
    this.editor = document.getElementById('editor');
    this.setupEventListeners();
  }
  
  setupEventListeners() {
    document.getElementById('openBtn').addEventListener('click', () => this.openFile());
    document.getElementById('saveBtn').addEventListener('click', () => this.saveFile());
    document.getElementById('saveAsBtn').addEventListener('click', () => this.saveAsFile());
  }
  
  async openFile() {
    try {
      [this.fileHandle] = await window.showOpenFilePicker();
      const file = await this.fileHandle.getFile();
      const contents = await file.text();
      this.editor.value = contents;
    } catch (err) {
      if (err.name !== 'AbortError') {
        console.error('打开文件失败:', err);
      }
    }
  }
  
  async saveFile() {
    if (!this.fileHandle) {
      await this.saveAsFile();
      return;
    }
    
    try {
      const writable = await this.fileHandle.createWritable();
      await writable.write(this.editor.value);
      await writable.close();
      alert('文件保存成功!');
    } catch (err) {
      console.error('保存文件失败:', err);
    }
  }
  
  async saveAsFile() {
    try {
      this.fileHandle = await window.showSaveFilePicker({
        suggestedName: 'untitled.txt',
        types: [{
          description: 'Text Files',
          accept: {'text/plain': ['.txt']}
        }]
      });
      
      await this.saveFile();
    } catch (err) {
      if (err.name !== 'AbortError') {
        console.error('另存文件失败:', err);
      }
    }
  }
}

// 初始化编辑器
new SimpleTextEditor();

9. 最佳实践与注意事项

  1. 错误处理：妥善处理用户取消操作的情况（AbortError）

  2. 性能优化：对于大文件操作，使用流式处理避免内存问题

  3. 渐进增强：为不支持的浏览器提供适当的回退方案

  4. 权限管理：定期检查权限状态，并在需要时重新请求

  5. 数据持久化：将文件句柄保存到 IndexedDB，实现会话间的持久访问

10. 总结与展望

File System Access API 标志着 Web 应用能力的重大进步，为构建功能丰富的 Web 应用打开了新的大门。虽然目前浏览器兼容性仍是主要挑战，但随着标准的成熟和更多浏览器的支持，这一 API 有望成为 Web 开发的标配工具。

对于开发者而言，理解并合理运用 File System Access API，可以创建出更强大、更接近桌面体验的 Web 应用，进一步模糊 Web 应用与原生应用之间的界限。在隐私和安全日益重要的今天，这一 API 提供的用户控制优先模型也为其广泛应用奠定了良好基础。

avatar
文章
阅读
粉丝