FileSystemHandle

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 的 FileSystemHandle 接口是代表一个文件或一个目录的对象。多个句柄可以代表同一个条目。在大多数情况下，你不会直接使用 FileSystemHandle，而是会用到它的 FileSystemFileHandle 和 FileSystemDirectoryHandle 子接口。

基于 FileSystemHandle 的接口

以下是基于 FileSystemHandle 的接口的列表。

FileSystemFileHandle

提供一个指向文件条目的句柄。

FileSystemDirectoryHandle

提供一个指向目录条目的句柄。

实例属性

kind 只读

返回条目的类型。如果关联的条目是一个文件，则此值为 'file'，否则为 'directory'。

name 只读

返回关联的条目的名称。

实例方法

isSameEntry()

比对两个句柄以查看两者关联的条目（文件或目录）是否相符。

queryPermission()

查询当前句柄目前的权限状态。

remove()

向底层文件系统请求移除句柄所代表的条目。

requestPermission()

为文件句柄请求读取或读写权限。

示例

检查类型

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

js
// 存放对文件句柄的引用
let fileHandle;

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

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

查询与请求权限

以下异步函数会在用户对文件句柄授予了只读或读写权限时返回 true，若无权限则请求权限。

js
// fileHandle 是一个 FileSystemFileHandle
// withWrite 是一个布尔值，如果要求写入则需传入 true

async function verifyPermission(fileHandle, withWrite) {
  const opts = {};
  if (withWrite) {
    opts.mode = "readwrite";
  }

  // 检查是否已经拥有相应权限，如果是，返回 true。
  if ((await fileHandle.queryPermission(opts)) === "granted") {
    return true;
  }

  // 为文件请求权限，如果用户授予了权限，返回 true。
  if ((await fileHandle.requestPermission(opts)) === "granted") {
    return true;
  }

  // 用户没有授权，返回 false。
  return false;
}

比对条目

以下函数将单个条目与条目数组进行比对，返回包含不相符条目的新数组。

js
function removeMatches(fileEntry, entriesArr) {
  const newArr = entriesArr.filter((entry) => !fileEntry.isSameEntry(entry));

  return newArr;
}

规范

Specification
File System Standard
# api-filesystemhandle

浏览器兼容性

BCD tables only load in the browser

参见