能力中的 API
registerProtocolHandler() 与 manifest 协议处理程序
发布于
协议处理器让 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 建立的关联;那一份随已安装应用一起移除。
另请参阅
链接到“另请参阅”一节- Manifest protocol_handlers,该成员自己的条目,含处理细节
- Manifest 文件处理程序(file_handlers),针对文件类型的同类操作系统注册
- 处理文件
- HTML Standard: registerProtocolHandler() method(html.spec.whatwg.org)
- HTML Standard: safelisted schemes(html.spec.whatwg.org)
- Web App Manifest incubations: protocol_handlers member(wicg.github.io)
- URL protocol handler registration for PWAs(developer.chrome.com)
- Handle protocols in Progressive Web Apps(learn.microsoft.com)
规范
- 图例
- 支持
- 部分支持
- 需开启标志
- 不支持
- 未知
| 浏览器 / 平台 | 支持 | 版本 | 置信度 | 来源 | 备注 |
|---|---|---|---|---|---|
| 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 |
- browser-compat-data 未记录 Chrome Android 的支持。
- 由 browser-compat-data 镜像自 Chrome 的数据推导。
- browser-compat-data 未记录 Firefox 的支持。
- browser-compat-data 未记录 Firefox for Android 的支持。
- 由 browser-compat-data 镜像自 Firefox 的数据推导。
- browser-compat-data 未记录 Safari 的支持。
- browser-compat-data 未记录 iOS 版 Safari 的支持。
- 由 browser-compat-data 镜像自 Safari 的数据推导。
- browser-compat-data 未记录 Samsung Internet 的支持。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
- browser-compat-data 未记录 WebView Android 的支持。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。