安装中的概念
安装后的应用快捷方式
发布于 更新于
应用快捷方式让用户从已安装 Web 应用的图标直接打开主要任务或页面。manifest 的 shortcuts 成员为
每个条目提供名称、目标 URL 和可选的展示数据。用户右键或长按应用图标时,浏览器可以把这些条目放进
上下文菜单。
兼容数据记录,Android 版 Chrome 84 起支持这个成员,Samsung Internet 列为镜像;桌面版 Chrome 与
Edge 96、macOS 版 Safari 17.4 起支持;iOS 版 Safari 与 Firefox 不支持(BCD
manifests.webapp.shortcuts)。
工作原理
链接到“工作原理”一节菜单依附于已安装应用。Chrome 文档说明,在 Windows 任务栏或 macOS Dock 里右键应用图标可以打开菜单, Android 则长按启动器图标。Microsoft Edge 把 manifest 快捷方式放进 Windows 跳转列表。macOS Sonoma 上的 Safari 17.4 会在“文件”菜单与 Dock 上下文菜单显示自定义命令。
浏览器决定展示多少条目以及如何展示。web.dev 记载,Windows 版 Chrome 与 Edge 最多显示 10 个, Android 版 Chrome 最多显示 3 个;MDN 也说明浏览器或操作系统可以截断数组。请把最重要的操作排在前面。 安装完成后,修改后的列表要等 manifest 更新算法运行才会进入平台菜单;仅修改 JSON 不保证菜单立即刷新。
每个快捷方式对象包含 name 和 url,还可以包含 short_name、description 与 icons。规范要求
url 相对 manifest URL 解析。manifest 位于 /dashboard/manifest.json 时,"url": "../projects"
因此指向 /projects。解析后的地址必须落在 manifest scope 内;处理算法会忽略超出 scope 的条目。
快捷方式图标与 manifest 主 icons 数组使用相同的图像资源成员。
用户选择快捷方式后,浏览器导航到条目的 url。请在应用界面里也保留这些目标,浏览器没有显示菜单时,
用户仍能完成同一任务。你可以给快捷方式 URL 加查询参数,用于路由或分析启动来源;web.dev 建议像标记
start_url 那样标记快捷方式 URL。
在 manifest 中声明两个快捷方式,并记录应用从哪个入口启动。不支持快捷方式的浏览器仍可使用应用内的相同链接。
避免快捷方式因超出 scope 而失效
链接到“避免快捷方式因超出 scope 而失效”一节manifest 位于 /app/manifest.webmanifest,所以相对 URL 解析到 /app/ 之下。每项带 ?source=shortcut 查询参数,便于应用归因启动来源。
{ "name": "Calendar", "start_url": "/app/", "scope": "/app/", "display": "standalone", "shortcuts": [ { "name": "New event", "short_name": "New", "description": "Create an event starting now", "url": "new-event?source=shortcut", "icons": [{ "src": "icons/new-event-96.png", "sizes": "96x96", "type": "image/png" }] }, { "name": "Today", "url": "today?source=shortcut", "icons": [{ "src": "icons/today-96.png", "sizes": "96x96", "type": "image/png" }] } ]}若改写成 "url": "/new-event",它会解析到 /app/ 之外。规范的处理算法会因目标超出 manifest
scope 而忽略这个条目。请把相对目标留在 /app/ 下;如果应用确实拥有外层目标,再有意扩大 scope。
判断由哪个快捷方式启动,并为无快捷方式的浏览器回退
链接到“判断由哪个快捷方式启动,并为无快捷方式的浏览器回退”一节应用启动时读取 location.pathname 与 source 查询参数,同时在应用菜单里保留同样的目标。即使已安装
应用菜单缺失或被截断,用户仍能从应用内部完成任务。
const url = new URL(location.href);const fromShortcut = url.searchParams.get('source') === 'shortcut';
if (fromShortcut && url.pathname.endsWith('/new-event')) { openEventEditor({ startsAt: Date.now() }); analytics.track('launch_shortcut', { shortcut: 'new-event' });} else { renderQuickActions([ { label: 'New event', href: '/app/new-event?source=menu' }, { label: 'Today', href: '/app/today?source=menu' }, ]);}
const installed = matchMedia('(display-mode: standalone)').matches;document.body.dataset.launchMode = installed ? 'standalone' : 'browser';应用自己控制两条路径里的 source 值。快捷方式分支记录 manifest 条目,回退分支渲染普通链接;这段代码
不会声称 JavaScript 能检测操作系统是否展示了快捷方式菜单。
菜单没有出现时定位问题
链接到“菜单没有出现时定位问题”一节先查shortcuts 兼容数据。如果数据把当前浏览器与操作系统组合标为不支持,修改 manifest 也不会增加这个菜单。在 Microsoft Edge 中打开 DevTools,依次选择 Application、Manifest,再滚动到快捷方式列表。Microsoft 把这个面板列为检查快捷方式配置的位置。预期条目没有出现在面板中时,应检查页面实际链接的 manifest 响应,不能只根据本地编辑过的文件判断线上内容。
const link = document.querySelector('link[rel="manifest"]');if (!link) throw new Error('No manifest link');
const response = await fetch(link.href);if (!response.ok) throw new Error(`Manifest HTTP ${response.status}`);
const manifest = await response.json();const documentURL = new URL(location.href);const parseURL = (value, base) => { if (typeof value !== 'string' || value === '') return null; try { return new URL(value, base); } catch { return null; }};const isWithinScope = (target, scope) => target.origin === scope.origin && target.pathname.startsWith(scope.pathname);
const startCandidate = parseURL(manifest.start_url, link.href);const startURL = startCandidate?.origin === documentURL.origin ? startCandidate : documentURL;const defaultScope = new URL('.', startURL);const scopeCandidate = parseURL(manifest.scope, link.href);if (scopeCandidate) { scopeCandidate.search = ''; scopeCandidate.hash = '';}const scope = scopeCandidate && isWithinScope(startURL, scopeCandidate) ? scopeCandidate : defaultScope;
console.info('Processed start URL and scope', { startURL: startURL.href, scope: scope.href });const shortcuts = Array.isArray(manifest.shortcuts) ? manifest.shortcuts : [];const rows = shortcuts.map((item) => { const target = parseURL(item?.url, link.href); return { name: item?.name, target: target?.href ?? 'invalid URL', validName: typeof item?.name === 'string' && item.name.trim() !== '', withinScope: target ? isWithinScope(target, scope) : false, };});console.table(rows);日志中的 URL 遵循 manifest 处理算法:start_url 缺失或不可用时回退为文档 URL;scope 缺失、不可用或与处理后的起始 URL 不兼容时,回退为起始 URL 的父路径。用表格查找缺失或为空的 name、无效 URL、相对错误 manifest 目录解析的 URL,以及落在处理后 scope 之外的目标。按规范处理快捷方式时,URL 超出 scope 会返回失败;name 缺失或为空也会返回失败。修正服务器实际返回的 manifest,等待浏览器处理 manifest 更新后,再查看 Application 面板。更新期间继续保留上个示例中的应用内普通链接,让用户无需依赖操作系统菜单也能到达相同页面。
另请参阅
链接到“另请参阅”一节- Web Application Manifest: shortcuts member(w3.org)
- Expose common app actions as shortcuts(developer.mozilla.org)
- Get things done quickly with app shortcuts(web.dev)
shortcutsmanifest 成员shortcuts浏览器支持- beforeinstallprompt 事件
scopemanifest 成员
规范
| 规范 | 状态 |
|---|---|
| Web 应用清单:shortcuts | W3C |
- 图例
- 支持
- 部分支持
- 需开启标志
- 不支持
- 未知
| 浏览器 / 平台 | 支持 | 版本 | 置信度 | 来源 | 备注 |
|---|---|---|---|---|---|
| Chrome (Android)# | 支持 | 85 | 低 | 来源 | — |
| Chrome (Desktop)# | 支持 | 96 | 低 | 来源 | — |
| Edge (Desktop)# | 支持 | 96 | 低 | 来源 | — |
| Samsung Internet# | 支持 | 14.0 | 低 | 来源 | — |
| Firefox (Desktop)# | 不支持 | — | 低 | 来源 | 1 |
| Safari (iOS)# | 不支持 | — | 低 | 来源 | 2 |
| Safari (macOS)# | 支持 | 17.4 | 低 | 来源 | — |
- 桌面版 Firefox 不支持 `shortcuts`。它的任务栏 web 应用(Windows,Firefox 143 起)由地址栏固定,而不是根据 manifest 安装。
- iOS 上不支持。