跳转到内容

Manifest 中的清单成员

protocol_handlers 清单成员

发布于 更新于

有限可用不支持的浏览器: Chrome (Android)、Firefox (Desktop)、Firefox (Android)、Safari (macOS)、Safari (iOS)W3C

清单成员 protocol_handlers 让浏览器在安装 Web 应用时,将它注册为操作系统的 URL 协议处理器。它的值是 { protocol, url } 对象数组。注册之后,在任何应用里点击 web+note:// 或 mailto: 链接都会在 url 处打开该 Web 应用,浏览器用完整链接替换 %s。

Chrome 96 与 Edge 96 为 Windows、macOS、Linux 上的桌面安装实现了该成员(BCD manifests.webapp.protocol_handlers)。Android 上的 Chrome、Samsung Internet、Firefox 157 与 Safari 27 不读取它。运行时 API navigator.registerProtocolHandler() 解决的是另一个场景:它把当前站点注册为 处理程序,浏览器可能要求用户确认;清单成员则在安装时注册,并与操作系统集成。

属性 值
类型 对象数组。每个对象有两个必填字符串:protocol,不带冒号的协议名;url,位于清单 scope 内、包含字面量 %s 的 HTTPS URL。相对 url 按清单 URL 解析。
默认值 空数组,不注册任何协议。
示例值 [{ "protocol": "web+note", "url": "/open?note=%s" }]。

protocol 必须是以 web+ 开头、后接小写 ASCII 字母的自定义协议,或是 HTML 标准安全列表中的协议: bitcoin、ftp、ftps、geo、im、irc、ircs、magnet、mailto、matrix、mms、 news、nntp、openpgp4fpr、sftp、sip、sms、smsto、ssh、tel、urn、webcal、 wtai 与 xmpp。浏览器会跳过其他值,例如 note 或 ms-word。

Chromium 解析器会丢弃格式错误的条目,保留数组中的其余项。 protocol_handlers entry ignored, required property 'protocol' is invalid. 与 protocol_handlers entry ignored, required property 'url' is invalid. 指出缺失的字段;url 里没有 占位符则产生 The url provided ('/open?note=') does not contain '%s'.。规范还会跳过 url 落在 scope 之外的条目,以及归一化后 url 与前面条目重复的条目。

注册以安装为单位:Chrome 在应用安装时把处理程序写入操作系统,卸载时移除。带该协议的链接第一次 启动应用时,Chrome 会先弹出一个写明应用名称的确认对话框再导航;多个应用声明同一协议时,操作系统 可能让用户选择默认程序。

处理页面需要检查传入值是否缺失、是否经过编码,以及协议是否符合预期。

为笔记应用注册自定义 web+ 协议

链接到“为笔记应用注册自定义 web+ 协议”一节

一款笔记应用声明 web+note,让邮件和聊天里的 web+note://2026-10-03 链接打开对应条目。url 位于 应用的 scope 之下,并把 %s 放在查询参数里,这样路径的其余部分保持静态。

{
"name": "Notebook",
"start_url": "/",
"scope": "/",
"display": "standalone",
"protocol_handlers": [
{ "protocol": "web+note", "url": "/open?note=%s" }
]
}

每个协议只注册一个处理程序;同一个 protocol 写两次、URL 不同时,保留第一条。

在处理页面上解码被替换进来的链接

链接到“在处理页面上解码被替换进来的链接”一节

浏览器用整条链接替换 %s,所以页面收到的是 web+note://2026-10-03 而不是 2026-10-03,其中 # 之类的字符被百分号编码。自己读取原始查询值并解码:URLSearchParams 会把 + 变成空格, 从而破坏 web+note。值缺失或携带别的协议时走回退分支,渲染普通页面,这也就是直接访问 /open 时的样子。

const raw = location.search.match(/[?&]note=([^&]*)/)?.[1];
let link = null;
try {
link = raw ? decodeURIComponent(raw) : null;
} catch {
link = null; // 百分号编码损坏:当作没有链接处理
}
if (link?.startsWith('web+note://')) {
openNote(link.slice('web+note://'.length)); // "2026-10-03"
} else {
showNoteList(); // 直接访问,或是本页不处理的协议
}

读取之后用 history.replaceState() 替换掉查询串,这样刷新或收藏不会再次触发处理逻辑。

在清单被忽略的环境回退到运行时 API

链接到“在清单被忽略的环境回退到运行时 API”一节

在没有该清单成员的浏览器里,navigator.registerProtocolHandler() 把当前站点注册为同一个协议的处理程序, 浏览器可能要求用户确认。从按钮点击中调用是合理的做法。对两者都做特性检测,并为运行时路径提供一个按钮。

export function offerProtocolRegistration(button) {
const installed = matchMedia('(display-mode: standalone)').matches;
if (installed) return; // Chrome/Edge 桌面端:清单已经注册了 web+note
if (typeof navigator.registerProtocolHandler !== 'function') return; // Safari:没有可用路径
button.hidden = false;
button.addEventListener('click', () => {
navigator.registerProtocolHandler('web+note', `${location.origin}/open?note=%s`);
});
}

Firefox 157 接受 web+ 协议的运行时注册。

规范

规范状态
清单协议处理器(protocol_handlers)W3C
Manifest Incubations: protocol_handlers memberWICG 草案
HTML Standard: safelisted schemesWHATWG 现行标准
  • 图例
  • 支持
  • 部分支持
  • 需开启标志
  • 不支持
  • 未知
浏览器 / 平台支持版本置信度来源备注
Chrome (Desktop)#支持96高来源—
Chrome (Android)#不支持—高来源1
Edge (Desktop)#支持96高来源2
Firefox (Desktop)#不支持—高来源3
Firefox (Android)#不支持—高来源45
Safari (macOS)#不支持—高来源6
Safari (iOS)#不支持—高来源78
Samsung Internet#不支持—高来源910
WebView (Android)#不支持—高来源1112
  1. browser-compat-data 未记录 Chrome Android 的支持。
  2. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  3. browser-compat-data 未记录 Firefox 的支持。
  4. browser-compat-data 未记录 Firefox for Android 的支持。
  5. 由 browser-compat-data 镜像自 Firefox 的数据推导。
  6. browser-compat-data 未记录 Safari 的支持。
  7. browser-compat-data 未记录 iOS 版 Safari 的支持。
  8. 由 browser-compat-data 镜像自 Safari 的数据推导。
  9. browser-compat-data 未记录 Samsung Internet 的支持。
  10. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
  11. browser-compat-data 未记录 WebView Android 的支持。
  12. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。

源数据: /compatibility/protocol-handlers.json · 全球使用占比: 39 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · MDN · 最近核验 2026-10-20 · 置信度: 高 (由来源计算)