# Manifest protocol_handlers：为 PWA 注册自定义 URL 协议

> manifest 的 protocol_handlers 成员如何将已安装的 PWA 注册为某个 URL 协议的处理程序、自定义协议的 web+ 命名规则，以及把点击的 URL 传入应用的 %s 占位符。

import CompatTable from '@components/CompatTable.astro';

**一句话：** manifest 的 `protocol_handlers` 成员将已安装的 PWA 注册为操作系统对某个
URL 协议（如 `mailto:`，或自定义的 `web+` 前缀协议）的处理程序，使点击匹配链接——无论
来自浏览器标签页、其他应用还是操作系统——都会带着该 URL 启动你的应用，而不是单纯导航。

## 这是什么

根据 MDN 的说明，`protocol_handlers` 是一个对象数组，每个对象包含必需的 `protocol`
（要处理的协议，例如 `mailto`、`ms-word` 或 `web+jngl`）和必需的 `url`（应用作用域内
的 HTTPS URL，其中 `%s` 占位符会被替换为完整的被点击 URL）。与操作系统的关联注册通常
发生在安装时，但根据 MDN 的说明，也可以在应用已安装之后再完成该关联。

## 支持情况

<CompatTable feature="protocol-handlers" />

在实现该特性的浏览器中，基于 manifest 的 `protocol_handlers` 注册均仅限桌面端；此外还
存在一个更早、独立的 `navigator.registerProtocolHandler()` API，可在页面中以命令式方式
注册处理程序，且不要求安装。

## 如何使用

在 manifest 中声明协议与 URL 模板：

```json
{
  "protocol_handlers": [
    {
      "protocol": "web+coffee",
      "url": "/coffee?type=%s"
    }
  ]
}
```

另外，MDN 为相关的、更早的 `navigator.registerProtocolHandler()` API 记录了一条命名
规则：其 `scheme` 参数必须以 `web+` 开头并至少跟一个小写 ASCII 字母（例如
`web+coffee`），或者必须是固定安全列表中的协议之一（如 `mailto`、`bitcoin`、`magnet`）。
manifest 的 `protocol_handlers` 页面本身并未对其 `protocol` 字段说明有此类命名限制。

安装并注册完成后，处理程序 URL 中的 `%s` 占位符会被以该处理程序协议开头的 URL 替换。

## 如何在运行时检测

根据 MDN 的说明，将协议与已安装应用关联通常在安装期间完成，但也可以在应用已安装之后
再完成该关联。页面能够检测的是另一个独立的命令式方法 `registerProtocolHandler()`
是否存在，适用于希望在安装之外也提供注册入口的站点：

```js
if ('registerProtocolHandler' in navigator) {
  navigator.registerProtocolHandler('web+coffee', '/coffee?type=%s');
} else {
  // 没有命令式注册 API——改为依赖 manifest 声明的 protocol_handlers
  // 关联，它会在安装时完成注册。
}
```

## 常见问题

- [ ] 基于 manifest 的 `protocol_handlers` 注册只有在应用**已安装**后才会生效——在普通
      浏览器标签页中打开的页面不会注册任何内容。
- [ ] MDN 所记录的 `web+` 前缀 / 安全列表命名规则适用于更早的 `registerProtocolHandler()`
      API 的 `scheme` 参数——其 manifest `protocol_handlers` 页面本身并未说明 `protocol`
      字段受到同样的限制。
- [ ] 根据 MDN 的说明，`url` 成员必须位于应用的 manifest 作用域内并使用 HTTPS——不能指向
      跨源地址。
- [ ] `%s` 占位符被替换为完整的被点击 URL，而不仅是解析后的负载——需要在处理路由中自行
      解析协议名之后的部分。

## 下一步

- [manifest: file_handlers 支持情况](/zh/compatibility/manifest-file-handlers/) —— 另一个
  将已安装 PWA 注册给操作系统的 manifest 成员，只是面向的是文件类型而非 URL 协议。
- [处理文件](/zh/guides/file-handling/) —— 一篇相关指南，介绍如何为已安装 PWA 注册操作
  系统级别的文件关联。