launch handler 是 web app manifest 中声明 pwa 启动行为的可选字段，仅在已安装、display 为 standalone/minimal-ui 的桌面端 pwa 通过系统入口启动时生效，依赖 manifest 配置和 launchqueue 监听。
不能直接用 HTML 控制 Launch Handler API 的窗口行为——它依赖 manifest.json 配置和 JavaScript 的 launchQueue 事件监听，且仅在 PWA 已安装、以 standalone 或 minimal-ui 模式启动时生效。
Launch Handler 是什么，以及它在哪起作用
Launch Handler 不是 HTML 标签或 DOM API，而是 Web App Manifest 中的一个可选字段，用于声明「当用户多次启动已安装的 PWA 时，系统应如何传递启动参数并复用/新建窗口」。它只在桌面端（Windows/macOS/Linux）的 PWA 安装后、通过开始菜单/桌面图标/文件关联等方式启动时触发。
关键前提：display 必须设为 standalone 或 minimal-ui；launch_handler 字段需存在于 manifest.json 中；浏览器支持（Chrome 119+、Edge 119+、Firefox 125+ 有限支持）。
manifest.json 中 launch_handler 的写法与常见错误
正确配置示例：
{
"display": "standalone",
"launch_handler": {
"client_mode": "focus-or-open"
}
}
注意以下易错点：
-
client_mode只接受两个字符串值："focus-or-open"（推荐）或"navigate"，拼写错误（如"focus_or_open"）会导致整个字段被忽略 - 必须放在顶层 manifest 对象中，不能嵌套在
display_override或其他字段下 - 若同时设置了
display: "browser"，launch_handler将完全不生效 - 某些旧版 Chrome（navigator.userAgentData?.brands 或
chrome.runtime?.id辅助判断运行环境
如何在 JS 中响应 launch 事件并控制窗口逻辑
仅靠 manifest 不够，你得用 launchQueue 在页面加载后注册回调：
在主 JS 文件（如 index.js）中尽早执行：
if ('launchQueue' in window) {
launchQueue.setConsumer((launchParams) => {
const url = launchParams.targetURL || '/';
const files = launchParams.files || [];
if (window.location.pathname === '/editor.html' && files.length > 0) {
// 复用当前窗口，导航到编辑页并载入文件
window.location.href = `/editor.html?file=${encodeURIComponent(files[0].name)}`;
return;
}
// 否则新开 tab 或 focus 现有窗口（由 manifest 中 client_mode 决定）
if (files.length > 0) {
console.log('Received files:', files);
}
});
}
重点说明：
-
launchQueue只在首次加载页面时可用，刷新后失效；不要在DOMContentLoaded之后才调用setConsumer -
targetURL来自快捷方式的url字段，files来自文件拖放或双击打开场景；两者都可能为空 - 不能在
setConsumer回调里调用window.open()强制新建窗口——这会绕过系统窗口管理逻辑，导致多开或权限拒绝 - 若想强制聚焦已有窗口，用
window.focus()；但能否成功取决于浏览器策略和当前窗口状态（如是否被最小化）
为什么你的 launch_handler 像没生效？几个真实踩坑点
最常被忽略的是环境验证环节：
- 未真正安装 PWA：地址栏没有「添加到桌面」按钮，或点击后没完成安装流程 →
launch_handler完全不触发 - 测试时用
http://localhost：部分浏览器（尤其是旧版 Edge）要求 HTTPS 才启用launchQueue - 修改了 manifest 但没清除浏览器缓存：PWA 安装后 manifest 会被缓存，需卸载重装或使用 DevTools → Application → Manifest → 「Update on reload」勾选后再刷新
- 在非启动路径下访问页面：比如用户从桌面图标启动，目标 URL 是
/dashboard，但你当前在/settings，此时launchQueue不会再次触发 —— 它只对「本次启动」有效
真正复杂的不是写法，而是验证链：HTTPS + 安装成功 + standalone 显示模式 + manifest 正确 + launchQueue 注册时机 + 浏览器版本支持 —— 少一环，就静默失败。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
