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

向操作系统注册应用，使其成为文件处理程序。

Thomas Steiner

现在，Web 应用能够读取和写入文件，因此下一步的合理做法是让开发者将这些 Web 应用声明为文件处理程序，以处理其应用可以创建和处理的文件。借助 File Handling API，您可以做到这一点。将文本编辑器应用注册为文件处理程序并安装后，您可以在 macOS 上右键点击 .txt 文件，然后选择“显示简介”，指示操作系统始终使用此应用作为默认应用来打开 .txt 文件。

File Handling API 的建议使用场景

以下是一些可能使用此 API 的网站示例：

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

如何使用 File Handling API

采用渐进增强的方式

File Handling API 本身无法进行 Polyfill。不过，您可以通过以下两种其他方式实现使用 Web 应用打开文件的功能：

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

浏览器支持

Browser Support

Source

功能检测

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

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

File Handling API 的声明性部分

首先，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) 文件，并在 /open-graf 处理扩展名为 .grafr、.graf 或 .graph 的虚构 Grafr 文件格式。前两个将在单个客户端中打开，如果正在处理多个文件，则最后一个将在多个客户端中打开。

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.
    }
  });
}

开发者工具支持

在撰写本文时，DevTools 尚不支持此功能，但我已提交功能请求，希望添加此支持。

演示

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

包含 Excalidraw 文件的 macOS 访达窗口。 — 在操作系统文件资源管理器中，双击或右键点击某个文件。

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

安全

Chrome 团队在设计和实现 File Handling API 时，遵循了控制对强大的 Web 平台功能的访问权限中定义的核心原则，包括用户控制、透明度和人机工程学。

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

为确保用户信任度和用户文件的安全性，当文件处理 API 打开文件时，系统会显示权限提示，然后 PWA 才能查看文件。此权限提示会在用户选择 PWA 打开文件后立即显示，因此该权限与使用 PWA 打开文件的操作紧密相关，从而使其更易于理解且更具相关性。

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

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

文件相关挑战

允许网站访问文件会带来很多攻击途径。这些内容在有关 File System Access API 的文章中进行了概述。与 File System Access API 相比，File Handling API 提供的额外安全相关功能是能够通过操作系统内置的界面授予对特定文件的访问权限，而不是通过 Web 应用显示的文件选择器授予访问权限。

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

默认处理程序挑战

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

用户控制

规范指出，浏览器不应将每个可以处理文件的网站都注册为文件处理程序。相反，文件处理注册应在安装后进行，并且绝不能在没有用户明确确认的情况下进行，尤其是在网站要成为默认处理程序的情况下。网站应考虑创建自己的扩展程序，而不是劫持现有扩展程序（例如用户可能已注册默认处理程序的 .json）。

透明度

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

反馈

Chrome 团队希望了解您在使用文件处理 API 方面的体验。

请告诉我们有关 API 设计的信息

API 是否存在未按预期运行的情况？或者，是否有缺少的方法或属性需要您来实现自己的想法？对安全模型有疑问或意见？

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

报告实现方面的问题

您是否发现 Chrome 的实现存在 bug？还是实现与规范不同？

在 new.crbug.com 上提交 bug。请务必尽可能详细地说明问题，提供简单的重现说明，并在组件框中输入 UI>Browser>WebAppInstalls>FileHandling。

显示对 API 的支持

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

在 WICG Discourse 帖子中分享您打算如何使用该功能。
使用 ##FileHandling 向 @ChromiumDev 发送推文，告诉我们您在何处以及如何使用该功能。

实用链接

致谢

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