FileSystemDirectoryHandle

Baseline 2023

Newly available

Since March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

安全上下文: 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

备注： 此特性在 Web Worker 中可用。

文件系统 API 的 FileSystemDirectoryHandle 接口提供指向一个文件系统目录的句柄。

这个接口可以通过 window.showDirectoryPicker()、StorageManager.getDirectory()、DataTransferItem.getAsFileSystemHandle() 和 FileSystemDirectoryHandle.getDirectoryHandle() 这些方法访问。

FileSystemHandle FileSystemDirectoryHandle

实例属性

从父接口 FileSystemHandle 继承属性。

实例方法

从父接口 FileSystemHandle 继承方法。

常规方法：

FileSystemDirectoryHandle.getDirectoryHandle()

返回一个 Promise，会兑现一个调用此方法的目录句柄内指定名称的子目录的 FileSystemDirectoryHandle。

FileSystemDirectoryHandle.getFileHandle()

返回一个 Promise，会兑现一个调用此方法的目录句柄内指定名称的文件的 FileSystemFileHandle。

FileSystemDirectoryHandle.removeEntry()

如果目录句柄包含一个名为指定名称的文件或目录，则尝试异步将其移除。

FileSystemDirectoryHandle.resolve()

返回一个 Promise 对象，会兑现一个包含从父目录前往指定子条目中间的目录的名称的数组。数组的最后一项是子条目的名称。

异步迭代器方法：

FileSystemDirectoryHandle.entries()

返回给定对象自己的可枚举属性的 [key, value] 对的新异步迭代器。

FileSystemDirectoryHandle.keys()

返回一个新的迭代 FileSystemDirectoryHandle 对象内每个条目的键的异步迭代器。

FileSystemDirectoryHandle.values()

返回一个新的迭代 FileSystemDirectoryHandle 对象内每个条目的句柄的异步迭代器。

FileSystemDirectoryHandle[Symbol.asyncIterator]()

返回给定对象自己的可枚举属性的 [key, value] 对的新异步迭代器。

示例

返回目录句柄

下面的示例返回一个指定名称的目录句柄，如果对应的目录不存在则创建。

js
const dirName = "directoryToGetName";

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

返回文件路径

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

js
async function returnPathDirectories(directoryHandle) {
  // 通过显示文件选择器来获得一个文件句柄
  const [handle] = await self.showOpenFilePicker();
  if (!handle) {
    // 如果用户取消了选择或者打开文件失败
    return;
  }

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

  if (relativePaths === null) {
    // 不在目录句柄中
  } else {
    // relativePaths 是一个包含名称的数组，指示相对路径

    for (const name of relativePaths) {
      // 打印数组的每个元素
      console.log(name);
    }
  }
}

返回目录中所有文件的句柄

下面的示例会递归地扫描一个目录，以返回目录中每个文件的 FileSystemFileHandle 对象：

js
async function* getFilesRecursively(entry) {
  if (entry.kind === "file") {
    const file = await entry.getFile();
    if (file !== null) {
      file.relativePath = getRelativePath(entry);
      yield file;
    }
  } else if (entry.kind === "directory") {
    for await (const handle of entry.values()) {
      yield* getFilesRecursively(handle);
    }
  }
}
for await (const fileHandle of getFilesRecursively(directoryHandle)) {
  console.log(fileHandle);
}

规范

Specification
File System Standard
# api-filesystemdirectoryhandle

浏览器兼容性

BCD tables only load in the browser

参见