# shortcuts 清单成员

> shortcuts 数组为已安装 PWA 图标的长按或右键菜单添加快捷操作条目，每一项直接打开一个作用域内的 URL，而不经过 start_url。

`shortcuts` 是一组快捷操作链接：用户长按（Android）或右键单击（Windows 任务栏、macOS Dock）
已安装应用的图标时，操作系统会把它们列在菜单里。每一项直接打开一个作用域内的 URL，绕过
`start_url`，相当于原生应用跳转列表的清单版："新建消息"、"收件箱"、"今天"这类高频目的地。

Android 上的 Chrome 85、桌面端的 Chrome 96 与 Edge 96、Samsung Internet 14.0 会读取该成员；
macOS 上的 Safari 17.4 为 Dock 应用加入了支持（BCD `html.manifest.shortcuts`）。iOS 上的 Safari
与 Firefox 157 不读取，在这些平台上条目被解析后即丢弃。

## 成员

- **类型**：快捷方式对象数组。每个对象包含 `name`（必填，菜单标签）、`url`（必填，相对清单 URL
  解析，且必须位于 `scope` 内），以及可选的 `short_name`、`description` 与 `icons`（与顶层
  `icons` 相同的图像对象形状）。
- **默认值**：空数组。非数组值会被解析器丢弃并提示 `property 'shortcuts' ignored, type array expected.`。
- **示例值**：`[{ "name": "新建发票", "url": "/app/invoice/new", "icons": [{ "src": "/icons/new-96.png", "sizes": "96x96" }] }]`。

Chromium 逐条校验。缺少 `name` 或 `url` 的条目被跳过，并提示
`property 'name' of 'shortcut' not present.` 或 `property 'url' of 'shortcut' not present.`；
`url` 超出作用域的条目被跳过，并提示 `property 'url' of 'shortcut' ignored. url should be within scope of the manifest.`
（`manifest_parser.cc`）。数组其余部分照常保留，所以一条坏条目只会少一个菜单项，不会整份菜单失效。

操作系统显示多少条是平台限制，不是清单限制：Android 启动器菜单显示 4 条，Windows 跳转列表 10 条，
macOS Dock 菜单 10 条（web.dev，"Get things done quickly with app shortcuts"）。Chromium 按顺序截断，
因此排在前面的条目在最紧的平台上才能保留。

:::observed
Chrome 155（macOS 26，英文界面）的 DevTools > Application > Manifest 中，**Shortcuts** 一节：`icons`
数组里没有 96 px 图像的条目会被标记为 `Shortcut #1 should include a 96×96 pixel icon`，该节始终带有一行
`The maximum number of shortcuts is platform dependent. Some shortcuts may be not available.`。
右键单击应用的 Dock 图标时，每个保留下来的 `name` 都列在标准的 **Options** 与 **Quit** 之上。
:::

## 示例

三个示例基于同一个 `scope` 为 `/app/` 的发票应用。

### 带图标与节省空间的 short_name 的三个操作

第一条写全了所有可选字段，第二条展示解析器接受的最小形式。Android 启动器空间不足时会用
`short_name` 替代 `name`，所以它应控制在一两个词内。

```json
{
  "scope": "/app/",
  "start_url": "/app/",
  "shortcuts": [
    {
      "name": "新建发票",
      "short_name": "新建",
      "description": "开始一张空白发票",
      "url": "/app/invoice/new?source=shortcut",
      "icons": [{ "src": "/icons/shortcut-new-96.png", "sizes": "96x96", "type": "image/png" }]
    },
    {
      "name": "未付发票",
      "url": "/app/invoices?filter=unpaid&source=shortcut",
      "icons": [{ "src": "/icons/shortcut-unpaid-96.png", "sizes": "96x96", "type": "image/png" }]
    },
    { "name": "仪表盘", "url": "/app/dashboard?source=shortcut" }
  ]
}
```

这里若写 `/billing/` 这样的 `url` 会因超出 `/app/` 而被丢弃；`description` 供辅助技术读取，不会绘制在菜单中。

### 不依赖专用 API 统计快捷方式启动次数

没有任何事件会告诉页面它是从快捷方式打开的，各条 `url` 上的查询串是唯一信号。启动时读一次，然后把它去掉，
免得应用内导航一直带着。参数不存在时，启动来自图标、链接或通知，代码什么也不记录。

```js
const params = new URLSearchParams(location.search);
if (params.get('source') === 'shortcut') {
  navigator.sendBeacon('/analytics', JSON.stringify({ launch: 'shortcut', path: location.pathname }));
  params.delete('source');
  const clean = `${location.pathname}${params.size ? `?${params}` : ''}${location.hash}`;
  history.replaceState(history.state, '', clean);
}
```

`history.replaceState()` 让返回按钮保持正常；没有它，应用内的第一次导航会把带标记的 URL 记成一条历史记录。

### 经得起菜单缩放的 96 px 单色图标

桌面菜单以 16 到 32 CSS 像素绘制快捷方式图标，且不做着色，细节繁多的多色图形会糊成一团。留足内边距的单色
PNG 在菜单用到的每个尺寸下都清晰可辨，每条一个 96 px 资源即可满足 DevTools 的检查。

```json
{
  "icons": [
    { "src": "/icons/shortcut-new-96.png", "sizes": "96x96", "type": "image/png" },
    { "src": "/icons/shortcut-new.svg", "sizes": "any", "type": "image/svg+xml" }
  ]
}
```

SVG 条目可选：存在时 Chromium 会把它栅格化，PNG 仍是 Windows 跳转列表的回退，因为跳转列表不接受 SVG。

## 另请参阅

- [安装后的应用快捷方式](/zh/reference/installation/install-shortcuts/)
- [添加应用快捷方式](/zh/guides/shortcuts/)
- [scope 清单成员](/zh/reference/manifest/scope/)
- [icons 清单成员](/zh/reference/manifest/icons/)
- [Web Application Manifest: shortcuts member](https://www.w3.org/TR/appmanifest/#shortcuts-member)（w3.org）
- [Get things done quickly with app shortcuts](https://web.dev/articles/app-shortcuts)（web.dev）