跳转到内容

安装中的概念

安装后的应用快捷方式

发布于 更新于

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

应用快捷方式让用户从已安装 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 应用清单:shortcutsW3C
  • 图例
  • 支持
  • 部分支持
  • 需开启标志
  • 不支持
  • 未知
浏览器 / 平台支持版本置信度来源备注
Chrome (Android)#支持85低来源—
Chrome (Desktop)#支持96低来源—
Edge (Desktop)#支持96低来源—
Samsung Internet#支持14.0低来源—
Firefox (Desktop)#不支持—低来源1
Safari (iOS)#不支持—低来源2
Safari (macOS)#支持17.4低来源—
  1. 桌面版 Firefox 不支持 `shortcuts`。它的任务栏 web 应用(Windows,Firefox 143 起)由地址栏固定,而不是根据 manifest 安装。
  2. iOS 上不支持。

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

来源: 规范 · MDN · 最近核验 2026-07-11 · 置信度: 低 (由来源计算)