此页面由 Cloud Translation API 翻译。

允许已安装的 Web 应用作为文件处理程序

在操作系统中将应用注册为文件处理程序。

Thomas Steiner

现在，Web 应用已经能够读取和写入文件，下一个逻辑步骤是让开发者将这些 Web 应用声明为其应用可创建和处理的文件的文件处理程序。File Handling API 正是为此而生的。将文本编辑器应用注册为文件处理程序并安装后，您可以在 macOS 上右键点击某个 .txt 文件，然后选择“Get Info”（获取信息），以指示操作系统应始终默认使用此应用打开 .txt 文件。

File Handling API 的建议用例

可能会使用此 API 的网站示例包括：

办公应用，例如文本编辑器、电子表格应用和幻灯片演示创建工具。
图形编辑器和绘图工具。
视频游戏关卡编辑器工具。

如何使用 File Handling API

渐进增强

无法对 File Handling API 本身进行 polyfill。不过，使用 Web 应用打开文件的功能还可通过另外两种方法实现：

借助 Web Share Target API，开发者可以将其应用指定为共享目标，以便从操作系统的共享表单中打开文件。
File System Access API 可与文件拖放功能集成，因此开发者可以在已打开的应用中处理拖放的文件。

浏览器支持

来源

功能检测

如需检查是否支持 File Handling API，请使用：

if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
  // The File Handling API is supported.
}

File Handling API 的声明性部分

首先，Web 应用需要在其Web 应用清单中以声明方式描述它们可以处理的文件类型。File Handling API 使用一个名为 "file_handlers" 的新属性扩展 Web 应用清单，该属性接受一组文件处理程序。文件处理程序是具有以下属性的对象：

"action" 属性，用于指向应用范围内的某个网址作为其值。
"accept" 属性，以 MIME 类型的对象作为键，并使用文件扩展名列表作为其值。
带有 ImageResource 图标数组的 "icons" 属性。某些操作系统允许文件类型关联显示一个图标，不仅仅是关联的应用图标，而是与该应用对相应文件类型的使用相关的特殊图标。
"launch_type" 属性，用于定义应在单个客户端还是多个客户端中打开多个文件。默认值为 "single-client"。如果用户打开多个文件，并且文件处理程序已使用 "multiple-clients" 作为 "launch_type" 进行注解，则会发生多个应用启动，并且每次启动时，LaunchParams.files 数组（请参阅向下部分）将只有一个元素。

以下示例（仅显示了 Web 应用清单的相关摘录）应该更清晰：

{
  "file_handlers": [
    {
      "action": "/open-csv",
      "accept": {
        "text/csv": [".csv"]
      },
      "icons": [
        {
          "src": "csv-icon.png",
          "sizes": "256x256",
          "type": "image/png"
        }
      ],
      "launch_type": "single-client"
    },
    {
      "action": "/open-svg",
      "accept": {
        "image/svg+xml": ".svg"
      },
      "icons": [
        {
          "src": "svg-icon.png",
          "sizes": "256x256",
          "type": "image/png"
        }
      ],
      "launch_type": "single-client"
    },
    {
      "action": "/open-graf",
      "accept": {
        "application/vnd.grafr.graph": [".grafr", ".graf"],
        "application/vnd.alternative-graph-app.graph": ".graph"
      },
      "icons": [
        {
          "src": "graf-icon.png",
          "sizes": "256x256",
          "type": "image/png"
        }
      ],
      "launch_type": "multiple-clients"
    }
  ]
}

这是一个假想应用，该应用处理位于 /open-csv 的逗号分隔值 (.csv) 文件、位于 /open-svg 的可缩放矢量图形 (.svg) 文件，以及处理 .grafr、.graf 或 .graph 中任何一项作为扩展名的合成 Grafr 文件格式。/open-graf前两个文件将在单个客户端中打开，后一个文件将在多个客户端中打开（如果处理多个文件）。

File Handling API 的必要部分

现在，应用已经声明了理论上可以在哪个作用域网址下处理哪些文件，因此在实际操作中，它需要以命令方式对传入文件执行某种操作。这正是 launchQueue 的用武之地。如需访问已启动的文件，网站需要为 window.launchQueue 对象指定使用方。启动会排入队列，直到指定的使用方处理它们为止（每次启动都恰好调用一次）。这样，每次启动都会得到处理，而不管是在何时指定使用方。

if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
  launchQueue.setConsumer((launchParams) => {
    // Nothing to do when the queue is empty.
    if (!launchParams.files.length) {
      return;
    }
    for (const fileHandle of launchParams.files) {
      // Handle the file.
    }
  });
}

开发者工具支持

在撰写本文时还没有开发者工具支持，但我已提交了功能请求，希望添加支持。

演示

我为卡通风格的绘图应用 Excalidraw 添加了文件处理支持。如需对其进行测试，你首先需要安装 Excalidraw。之后，当您使用该文件创建文件并将其存储在文件系统的某个位置时，您可以通过双击或右键点击打开该文件，然后在上下文菜单中选择“Excalidraw”。您可以在源代码中查看 implementation。

包含 Excalidraw 文件的 macOS 查找器窗口。 — 双击或右键点击操作系统的文件资源管理器中的文件。

右键点击某个文件时显示的上下文菜单，其中“打开方式...”选项为 Excalidraw 项。 — Excalidraw 是 `.excalidraw` 文件的默认文件处理程序。

安全性

Chrome 团队按照控制对强大 Web 平台功能的访问权限中定义的核心原则（包括用户控制、透明度和工效学设计）设计和实现了 File Handling API。

权限、权限持久性和文件处理程序更新

为了确保用户信任和用户文件的安全，当 File Handling API 打开文件时，系统会在 PWA 查看文件之前显示权限提示。此权限提示将在用户选择 PWA 打开文件后立即显示，以便权限与使用 PWA 打开文件的操作紧密耦合，从而使其更易于理解且更相关。

此权限每次都会显示，直到用户点击允许或禁止网站处理文件，或者忽略提示三次（之后 Chromium 将禁用并阻止此权限）。所选设置在关闭并重新打开 PWA 后仍会保留。

当检测到清单更新和 "file_handlers" 部分中的更改时，权限将会重置。

与文件相关的验证

允许网站访问文件即可打开一大类攻击途径。File System Access API 的相关文章介绍了这些操作。File Handling API 通过 File System Access API 提供一项额外的安全相关功能，那就是能够通过操作系统的内置界面（而不是通过 Web 应用显示的文件选择器）授予对某些文件的访问权限。

但用户仍然可能会因为打开文件而无意中授予 Web 应用访问权限。不过，一般可以理解，打开文件会允许打开文件的应用读取和/或操作该文件。因此，用户明确选择在已安装的应用中打开文件（例如通过“打开方式...”上下文菜单）可以视为对应用的信任充分信号。

默认处理程序验证

例外情况是，主机系统上没有适用于给定文件类型的应用。在这种情况下，某些主机操作系统可能会以静默方式自动将新注册的处理程序提升为相应文件类型的默认处理程序，而无需用户进行任何干预。这意味着，如果用户双击该类型的文件，则会自动在已注册的 Web 应用中打开。在此类主机操作系统上，当用户代理确定该文件类型目前没有默认处理程序时，可能需要显示明确的权限提示，以避免在未经用户同意的情况下将文件内容意外发送到 Web 应用。

用户控制

该规范指出，浏览器不应将可以将文件处理为文件处理程序的所有网站都注册。相反，文件处理注册应该受安装控制，并且绝不会在没有用户明确确认的情况下发生，尤其是在网站要成为默认处理程序的情况下。网站应考虑创建自己的扩展程序，而不是劫持像 .json 这样的现有扩展程序，而用户可能已经注册了默认处理程序。

透明度

所有操作系统都允许用户更改当前文件关联。这不在浏览器的范围内。

反馈

Chrome 团队希望了解您使用 File Handling API 的体验。

向我们介绍 API 设计

是否存在 API 行为不符合您预期的情况？或者说，是否缺少某些方法或属性来实现您的想法？如果您对安全模型有疑问或意见，

在相应的 GitHub 代码库中提交规范问题，或将您的想法添加到现有问题中。

报告实施方面的问题

您是否发现了 Chrome 实现方面的错误？或者，实现方式是否不同于规范？

在 new.crbug.com 上提交 bug。请务必提供尽可能多的详情和简单的重现说明，并在组件框中输入 UI>Browser>WebAppInstalls>FileHandling。Glitch 非常适合快速轻松地分享重现错误。

显示对该 API 的支持

打算使用 File Handling API 吗？您的公开支持有助于 Chrome 团队确定功能优先级，并向其他浏览器供应商表明支持这些功能的重要性。

请在 WICG Discourse 会话中说明您打算如何使用该工具。
请使用 # 标签 #FileHandling 在 Twitter 上向 @ChromiumDev 发送一条推文，告诉我们您使用该推文的位置和方式。

实用链接

致谢

File Handling API 由 Eric Willigers、Jay Harris 和 Raymes Khoury 指定。本文由 Joe Medley 审核。