大网数据广告活动
Web 标准与前端开发

Window:showOpenFilePicker() 方法

· 52CE 我爱测

Window 接口的 **`showOpenFilePicker()`** 方法用于显示一个允许用户选择一个或多个文件的文件选择器,并返回这些文件的句柄。

File System API

Window 接口的 showOpenFilePicker() 方法用于显示一个允许用户选择一个或多个文件的文件选择器,并返回这些文件的句柄。

语法

showOpenFilePicker()
showOpenFilePicker(options)

参数

  • options
    • : 选项对象,包含以下属性:
      • excludeAcceptAllOption
        • : 布尔值,默认为 false。默认情况下,选择器应包含一个不应用任何文件类型过滤器的选项(通过下面的类型选项启动)。将此选项设置为 true 意味着该选项不可用。
      • id
        • : 通过指定 ID,浏览器可以记住不同 ID 所对应的目录。如果在另一个选择器中使用了相同的 ID,则选择器将在同一目录中打开。
      • multiple
        • : 布尔值,默认为 false。当设置为 true 时,可以选择多个文件。
      • startIn
        • : 一个 FileSystemHandle 对象或一个众所周知的目录("desktop"、"documents"、"downloads"、"music"、"pictures" 或 "videos")以指定打开选择器的起始目录。
      • types
        • : 允许选择的文件类型的Array。每个项目都是一个具有以下选项的对象:
          • description
            • : 允许的文件类型类别的可选描述。默认为空字符串。
          • accept
            • : 一个 Object,其键设置为 MIME 类型,值设置为文件扩展名的Array(参见下面的示例)。

返回值

一个 Promise 对象,其兑现一个包含 FileSystemFileHandle 对象的Array。

异常

  • AbortError DOMException
    • : 如果用户在没有做出选择的情况下关闭提示,或者如果用户代理认为任何选定的文件过于敏感或危险,则抛出此异常。
  • SecurityError DOMException
    • : 如果调用被同源策略阻止,或者不是通过用户交互(例如按下按钮)调用,则抛出该异常。
  • TypeError
    • : 如果无法处理接受类型,则抛出该异常,它可能会在出现以下情况时发生:
      • types 选项中任何项目的 accept 选项的任何键字符串都无法解析为有效的 MIME 类型。
      • types 选项中任何项目的 accept 选项的任何值字符串都是无效的,例如,如果它不以 . 开头,或者它以 . 结尾,或者它包含任何无效的值码点且长度大于 16。
      • types 选项为空,excludeAcceptAllOption 选项为 true。

安全性

瞬态用户激活是必需的。用户必须与页面或 UI 元素进行交互才能使该特性正常运行。

示例

在此处我们设置一个用于传递给方法的选项对象。我们将允许选择图片类型、不允许使用所有类型,也不能选择多个文件。

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

接下来我们创建一个异步函数来显示文件选择器并返回选择的文件。

// 创建用于存放文件句柄的引用。
let fileHandle;

async function getFile() {
  // 打开文件选择器,解构返回的数组中的第一个元素
  [fileHandle] = await window.showOpenFilePicker(pickerOpts);

  // 操作 fileHandle 的后续代码
}

规范

浏览器兼容性

参见

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。