跳转到内容

能力中的 API

registerProtocolHandler() 与 manifest 协议处理程序

发布于

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

协议处理器让 Web 应用打开 mailto:、web+music: 等协议的链接。navigator.registerProtocolHandler(scheme, url) 由页面调用,在普通标签页里就能用,浏览器可能在注册时或链接激活时请求用户确认;manifest 的 protocol_handlers 成员在 PWA 安装时处理,不需要页面调用,Manifest Incubations 草案建议用户代理在把处理器设为操作系统默认之前征求用户许可。两者都按 HTML 标准的「normalize protocol handler parameters」步骤处理,协议和 URL 规则相同。遇到无效值,方法会抛出异常,manifest 则直接丢弃该值,不报告错误。

registerProtocolHandler() 在桌面端 Firefox 2 与 Chrome 13 起就有,Edge 79 与 Opera 11.6 跟进;Chrome 77 起 url 只接受 http: 与 https:。Safari 没有实现,Android 版 Chrome 不暴露它,而 Android 版 Firefox 的支持情况与桌面 Firefox 相同(BCD api.Navigator.registerProtocolHandler)。unregisterProtocolHandler() 只存在于 Chromium,始于 Chrome 38。manifest 成员是 Chrome 96 与 Edge 96 的桌面专属功能,完整支持情况见兼容性表。

navigator.registerProtocolHandler(scheme, url)
navigator.unregisterProtocolHandler(scheme, url)
{
"protocol_handlers": [
{ "protocol": "web+music", "url": "/play?song=%s" }
]
}

两个方法都返回 undefined。调用返回后,注册过程并行运行,没有可等待的 Promise,也无法得知用户是否接受了提示。两者都带 [SecureContext],url 的同源要求本身也蕴含了这一点。激活带已注册协议的链接时,浏览器把完整链接做百分号编码、替换掉 %s,然后在新的顶层浏览上下文中导航到结果。

方法参数与 manifest 条目成员一一对应。

方法参数 manifest 成员 类型 必填 说明
scheme protocol DOMString 是 检查前先转小写。必须是安全名单内的协议,或以 web+ 开头后接一个或多个小写 ASCII 字母(web+music 可以,web+music2 与 web+ 不行)。末尾带冒号即无效。
url url DOMString 是 必须包含字面量 %s。方法按文档解析、成员按 manifest URL 解析;结果必须是文档同源的 http: 或 https: URL,manifest 还要求位于其 scope 之内。

安全名单内的协议是 bitcoin、ftp、ftps、geo、im、irc、ircs、magnet、mailto、matrix、mms、news、nntp、openpgp4fpr、sftp、sip、sms、smsto、ssh、tel、urn、webcal、wtai 与 xmpp。manifest 处理时会跳过缺少 protocol 或 url、规范化失败、超出 scope,或 url 与前面条目重复的项,并且不报告原因。

registerProtocolHandler() 与 unregisterProtocolHandler() 同步抛出。manifest 成员不抛异常,浏览器会在处理阶段丢弃无效条目。

异常 条件
SecurityError scheme 既不在安全名单内,也不是 web+ 加小写字母,包括带冒号的 "mailto:";解析后的 url 不是 http: 或 https:,或与文档不同源;浏览器拦截了注册,例如注册 http 本身。Chrome 还会在 Isolated Web App 中抛出,并提示改用 manifest 成员。
SyntaxError url 不含 %s;url 解析失败,%s 位于 host 或端口时必然如此。

示例为部署在 https://player.example/ 的播放器注册 web+music。处理路由是 /play?song=%s,点击 web+music:track/42 会在该源打开 /play,song 参数经 URLSearchParams 解码后仍是 web+music:track/42。

在设置页提供注册入口并给出手动回退

链接到“在设置页提供注册入口并给出手动回退”一节

先检测方法是否存在,再同时捕获两个异常名:SecurityError 表示浏览器拦截了注册,例如协议无效或处理器 URL 在另一个源,而用户拒绝任何确认时页面根本不会知道。Safari 和 Android 版 Chrome 走回退分支,向用户说明如何改为粘贴链接。

const button = document.querySelector("#register-handler");
if (typeof navigator.registerProtocolHandler !== "function") {
button.hidden = true;
document.querySelector("#paste-link-help").hidden = false;
} else {
button.addEventListener("click", () => {
try {
navigator.registerProtocolHandler("web+music", "/play?song=%s");
button.textContent = "已请求,请在浏览器提示中确认";
} catch (err) {
if (err.name === "SecurityError" || err.name === "SyntaxError") {
console.error(`${err.name}: ${err.message}`);
} else {
throw err;
}
}
});
}

HTML 标准要求浏览器记住用户拒绝过的注册,不再重复提示,所以拒绝后再点一次可能毫无反应;在按钮的帮助文字里把这一点说清楚。

在 manifest 中声明同一处理程序并读取启动 URL

链接到“在 manifest 中声明同一处理程序并读取启动 URL”一节

manifest 带上该条目后,已安装的用户无需页面调用即可通过该条目获得关联。路由在 song 查询参数里收到整条链接(含协议),需要自己去掉前缀。

{
"name": "Player",
"start_url": "/",
"scope": "/",
"protocol_handlers": [
{ "protocol": "web+music", "url": "/play?song=%s" }
]
}
const launched = new URL(location.href).searchParams.get("song");
if (launched && launched.startsWith("web+music:")) {
const trackId = launched.slice("web+music:".length); // "track/42"
loadTrack(trackId);
} else {
showLibrary(); // 直接打开,而不是通过协议链接
}

路由要放在 manifest 的 scope 之内:浏览器处理 manifest 时会丢弃超出 scope 的 url,安装照常完成,却没有处理程序,也没有任何警告。

unregisterProtocolHandler() 接受同样的两个参数,只存在于 Chromium。要和 registerProtocolHandler() 分开检测,因为 Firefox 有 registerProtocolHandler(),没有 unregisterProtocolHandler()。

function forgetHandler() {
if (typeof navigator.unregisterProtocolHandler !== "function") {
return false; // Firefox:只能在浏览器自己的设置里移除
}
navigator.unregisterProtocolHandler("web+music", "/play?song=%s");
return true;
}

通过方法取消注册不影响 manifest 建立的关联;那一份随已安装应用一起移除。

规范

规范状态
清单协议处理器(protocol_handlers)W3C
HTML Standard: registerProtocolHandler() methodWHATWG 现行标准
HTML Standard: normalize protocol handler parametersWHATWG 现行标准
Web App Manifest incubations: protocol_handlers memberWICG 草案
  • 图例
  • 支持
  • 部分支持
  • 需开启标志
  • 不支持
  • 未知
浏览器 / 平台支持版本置信度来源备注
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 · 置信度: 高 (由来源计算)