File System Access API - 提供了读取、写入和文件管理功能

安全上下文
该功能仅在部分或所有支持的浏览器中的安全上下文（HTTPS）中可用。

File System Access API（文件系统访问 API）提供了读取、写入和文件管理功能。

概念和用法

此 API 允许与用户本地设备或用户可访问的网络文件系统上的文件进行交互。此 API 的核心功能包括读取文件、写入或保存文件以及访问目录结构。

大多数与文件和目录的交互是通过句柄完成的。从父类句柄 FileSystemHandle 继承了两个子类：FileSystemFileHandle 和 FileSystemDirectoryHandle，分别用于文件和目录。

这些句柄表示用户系统上的文件或目录。您必须首先通过向用户显示文件或目录选择器来访问它们。可以通过 window.showOpenFilePicker 和 window.showDirectoryPicker 来显示文件或目录选择器，然后用户选择一个文件或目录。一旦选择完成，将返回一个句柄。您还可以通过 HTML Drag and Drop API 的 DataTransferItem.getAsFileSystemHandle() 方法访问文件句柄。

句柄提供了相应的功能，根据选择的是文件还是目录而有一些差异（有关具体详细信息，请参阅 接口 部分）。然后，您可以访问所选目录的文件数据或信息（包括子目录）。

还有 “保存” 功能，使用的是 FilesystemWritableFileStream 接口。一旦您要保存的数据格式为 Blob, USVString 或 buffer，您可以打开流并将数据保存到文件中。可以保存现有文件或新文件。

这个 API 开辟了网络一直缺乏的潜在功能。尽管如此，在设计 API 时，安全性一直是最重要的问题，除非用户特别允许，否则不允许访问文件 / 目录数据。

接口

FileSystemHandle

FileSystemHandle 接口是一个表示条目的对象。多个句柄可以表示同一个条目。大多数情况下，您不直接使用 FileSystemEntry ，而是使用它的子接口 FileSystemFileEntry 和 FileSystemDirectoryEntry。

FileSystemFileHandle

提供文件系统条目的句柄。

FileSystemDirectoryHandle

提供文件系统目录的句柄。

FileSystemWritableFileStream

一个带有额外便利方法的 WritableStream 对象，它对磁盘上的单个文件进行操作。

实例

访问文件

下面的代码允许用户从文件选择器中选择一个文件，然后测试返回的句柄是文件还是目录

// 存储对我们文件句柄的引用
let fileHandle;

async function getFile() {
  // 打开文件选择器
  [fileHandle] = await window.showOpenFilePicker();

  if (fileHandle.kind === 'file') {
    // 运行文件代码
  } else if (fileHandle.kind === 'directory') {
    // 运行目录代码
  }

}

下面的异步函数提供了一个文件选择器，一旦选择了一个文件，就会使用 getFile() 方法来检索内容。

const pickerOpts = {
  types: [
    {
      description: 'Images',
      accept: {
        'image/*': ['.png', '.gif', '.jpeg', '.jpg']
      }
    },
  ],
  excludeAcceptAllOption: true,
  multiple: false
};

async function getTheFile() {
  // 打开文件选择器
  [fileHandle] = await window.showOpenFilePicker(pickerOpts);

  // 获取文件内容
  const fileData = await fileHandle.getFile();
}

访问目录

以下实例返回具有指定名称的目录句柄。如果该目录不存在，则创建它。

const dirName = 'directoryToGetName';

// 假设我们有一个目录句柄：'currentDirHandle'
const subDir = currentDirHandle.getDirectoryHandle(dirName, {create: true});

下面的异步函数使用 resolve() 来查找相对于指定目录句柄的所选文件的路径。

async function returnPathDirectories(directoryHandle) {

  // 通过显示文件选择器获取文件句柄：
  const handle = await self.showOpenFilePicker();
  if (!handle) {
    // 用户取消，或无法打开文件。
    return;
  }

  // 检查我们的目录句柄目录中是否存在句柄
  const relativePaths = await directoryHandle.resolve(handle);

  if (relativePath === null) {
    // 不在目录句柄内
  } else {
    // relativePath 是一个名称数组，包含了相对路径
    for (const name of relativePaths) {
      // 记录每个条目
      console.log(name);
    }
  }
}

写入文件

下面的异步函数打开保存文件选择器，一旦选择了一个文件，它就会返回一个 FileSystemFileHandle。然后使用 FileSystemFileHandle.createWritable() 方法创建可写流。

然后将用户定义的 Blob 写入随后关闭的流中。

async function saveFile() {

  // 创建一个新的句柄
  const newHandle = await window.showSaveFilePicker();

  // 创建要写入的 FileSystemWritableFileStream
  const writableStream = await newHandle.createWritable();

  // 写入我们的文件
  await writableStream.write(imgBlob);

  // 关闭文件并将内容写入磁盘。
  await writableStream.close();
}

下面显示了可以传递给 write() 方法的选项的不同实例。

// 只需传入数据（无选项）
writableStream.write(data)

// 从确定的位置将数据写入流
writableStream.write({ type: "write", position: position, data: data })

// 将当前文件游标偏移更新到指定的位置
writableStream.write({ type: "seek", position: position })

// 将文件大小调整为 size 字节长
writableStream.write({ type: "truncate", size: size })

规范

规范 状态 备注
Unknown Unknown 初始定义。

桌面浏览器兼容性

暂无兼容数据

相关链接