跳转到内容

Manifest 中的清单成员

launch_handler 清单成员

发布于

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

清单成员 launch_handler 决定已安装 Web 应用再次启动时怎样处理现有窗口。启动可以来自系统启动器、快捷方式、文件关联、协议链接或分享。它只提供 client_mode 属性,用来选择聚焦现有窗口、将其导航到启动 URL,或新开窗口。

Chrome 110、Edge 110、Samsung Internet 21.0 与 Android WebView 110 实现了该成员(BCD manifests.webapp.launch_handler)。兼容性数据记录 Firefox 与 Safari 不支持该成员, 所以不应在那里依赖它。window.launchQueue 将启动 URL 送达页面,focus-existing 正是靠它才有用。

属性 值
类型 对象,只有一个属性 client_mode,取字符串或字符串数组。允许的值:auto、navigate-new、navigate-existing、focus-existing
默认值 auto。成员缺省、client_mode 不是字符串或数组、数组里没有任何可识别的值,这三种情况都解析为 auto
示例值 { "client_mode": ["focus-existing", "auto"] }

已有窗口打开时,各模式的行为:

  • auto 把选择权交给浏览器。Chromium 在 Android 上取 navigate-existing(单实例是常态), 在桌面端取 navigate-new。
  • navigate-new 在启动 URL 处新开应用窗口。
  • navigate-existing 把最近使用的窗口提到前台,并让它导航到启动 URL。
  • focus-existing 把该窗口提到前台但不导航。页面从 launchQueue 收到启动 URL,自行决定 怎么处理。

没有窗口打开时,focus-existing 与 navigate-existing 的表现等同于 navigate-new。值为数组时, 浏览器按顺序取首个可识别值,因此清单可以优先 focus-existing,同时为将来新增模式的引擎写上 auto。

Chromium 解析器要求值符合指定类型。非对象值会产生 launch_handler value ignored, object expected.,client_mode 中的未知字符串会产生 client_mode value '<value>' ignored, unknown value.(manifest_parser.cc 的 ParseLaunchHandler)。解析器跳过无效条目,继续处理这个成员。

清单只需一行设置;启动交给现有窗口后,由 launchQueue 消费者处理,focus-existing 才能完成相应操作。

保持单一编辑器窗口并把启动导入其中

链接到“保持单一编辑器窗口并把启动导入其中”一节

文档编辑器可以用 focus-existing 保留单一窗口,收到启动请求后切换到相应文档。页面收到启动 URL 后更新自身状态。

{
"name": "Draft",
"start_url": "/",
"display": "standalone",
"launch_handler": { "client_mode": ["focus-existing", "auto"] },
"file_handlers": [
{ "action": "/open", "accept": { "text/markdown": [".md"] } }
]
}
if ('launchQueue' in window) {
window.launchQueue.setConsumer(async (launchParams) => {
const url = new URL(launchParams.targetURL);
if (launchParams.files.length > 0) {
const file = await launchParams.files[0].getFile();
await openDocument(file);
return;
}
const doc = url.searchParams.get('doc');
if (doc) await openDocumentById(doc);
});
} else {
// 没有 launchQueue:浏览器做的是普通导航,直接读 URL 即可。
const doc = new URL(location.href).searchParams.get('doc');
if (doc) await openDocumentById(doc);
}

启动并创建窗口时会调用一次消费者;后续启动路由到这个窗口时,消费者会再次运行。启动来自文件关联时,launchParams.files 是 FileSystemFileHandle 数组,否则为空。

调用 setConsumer() 之前先检查 window.launchQueue。这个检查只能确认接口存在,因为 MDN 的兼容性数据把 LaunchQueue 与 launch_handler 清单成员分开记录。没有 launchQueue 时,辅助函数改读 location;只有启动确实让页面导航了,location 才是启动 URL,而 focus-existing 不会导航现有页面。辅助函数用同一回调处理这两种情况。

export function onLaunch(handler) {
if ('launchQueue' in window) {
window.launchQueue.setConsumer((params) => handler(new URL(params.targetURL)));
} else {
handler(new URL(location.href));
}
}
onLaunch((url) => {
if (url.pathname === '/share') showShareSheet(url.searchParams);
});

在模块首次 await 之前注册消费者。Chromium 会暂存启动参数,等消费者注册后再交付;晚注册会延迟处理,但不会丢失参数。

桌面端偏好新窗口、移动端偏好现有窗口

链接到“桌面端偏好新窗口、移动端偏好现有窗口”一节

新闻阅读器希望桌面端启动时各开窗口,手机端则共用单一窗口。auto 在 Chromium 里已经编码了这种区分,清单把它显式写出来,把选择交给浏览器。

{
"launch_handler": { "client_mode": "auto" }
}

写出 auto 和省略该成员效果相同。显式保留它,日后修改清单时就能直接在这里改模式。

规范

规范状态
Web 应用清单:launch_handlerWICG 草案
  • 图例
  • 支持
  • 部分支持
  • 需开启标志
  • 不支持
  • 未知
浏览器 / 平台支持版本置信度来源备注
Chrome (Desktop)#支持110高来源—
Chrome (Android)#支持110高来源1
Edge (Desktop)#支持110高来源2
Firefox (Desktop)#不支持—高来源3
Firefox (Android)#不支持—高来源45
Safari (macOS)#不支持—高来源6
Safari (iOS)#不支持—高来源78
Samsung Internet#支持21.0高来源9
WebView (Android)#支持110高来源10
  1. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  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 镜像自 Chrome Android 的数据推导。
  10. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。

源数据: /compatibility/manifest-launch-handler.json · 全球使用占比: 75 % (StatCounter 2026-09, CC BY-SA 4.0)

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