# 添加应用快捷方式

> 一份分步指南：如何在 PWA manifest 中添加 shortcuts 条目，让已安装应用的图标提供快速跳转到关键页面的入口。

import CompatTable from '@components/CompatTable.astro';

**一句话概括：** manifest 的 `shortcuts` 成员让 PWA 图标呈现一个上下文菜单（例如通过右键
点击或长按触发），其中包含若干快捷操作入口，选择其中之一即可直接跳转到某个作用域内的 URL。

## 1. 在 manifest 中声明 shortcuts

根据 W3C 规范，`shortcuts` 数组中的每一项都需要 `name` 与 `url`；`short_name`、
`description`、`icons` 则是可选的：

```json
{
  "shortcuts": [
    {
      "name": "New Invoice",
      "short_name": "New",
      "description": "Create a new invoice",
      "url": "/app/invoice/new",
      "icons": [
        { "src": "/icons/shortcut-new.png", "sizes": "96x96", "type": "image/png" }
      ]
    },
    {
      "name": "Dashboard",
      "url": "/app/dashboard"
    }
  ]
}
```

## 2. 让每个快捷方式的 url 都保持在 scope 内

W3C 规范要求每个快捷方式的 `url` 都必须位于 manifest 的 `scope` 之内；超出 `scope` 的
`url` 不会被采纳。在这一约束之内，MDN 将快捷方式描述为直接跳转到一个高频使用的功能或
页面——规范并未同时要求该目的地也能从应用的常规内部导航中到达，因此只要保持在作用域内，
一个"仅通过快捷方式进入"的入口也是允许的。

## 浏览器与生态支持

<CompatTable feature="manifest-shortcuts" />

根据 Can I Use 的数据，`shortcuts` manifest 成员的全球浏览器使用量支持率约为 80%
（79.97% 完全支持 + 0.05% 部分支持），因此应将操作系统快捷方式菜单视为常规导航之上的
一层便利入口，而不是通往某功能的唯一路径。

## 检测支持情况并提供回退

根据 W3C 规范，由用户代理或操作系统决定快捷方式如何呈现、以及向用户展示多少条快捷方式——
没有任何 JavaScript API 能报告当前浏览器或操作系统是否会展示操作系统级别的快捷方式菜单。
页面能检测的只是自己的 manifest 对象，在使用前对缺失或格式错误的 `shortcuts` 数组做好防御：

```js
function hasDeclaredShortcuts(manifest) {
  if (!('shortcuts' in manifest) || !Array.isArray(manifest.shortcuts) || manifest.shortcuts.length === 0) {
    // manifest 中未声明 shortcuts —— 操作系统菜单也就无从展示。
    return false;
  }
  return true;
}
```

这只能确认你自己的 manifest 声明了什么，并不能确认访问者的浏览器与操作系统是否真的会展示
该菜单——因此真正的回退是无条件的：无论 `hasDeclaredShortcuts()` 的结果如何，都应始终渲染
一个始终可见的应用内快速操作菜单作为配套入口，让每一位访问者无论其浏览器与操作系统是否也
提供操作系统级别的菜单，都能获得等效的访问能力。

## 常见问题

- [ ] 每个快捷方式的 `url` 都位于 manifest 的 `scope` 之内——根据 W3C 规范，超出作用域
      的 url 不会被采纳。
- [ ] 每个条目都必须提供 `name`；保持足够简短，以便在支持的最窄平台上也不会被截断。
- [ ] 按重要性排列快捷方式——根据 W3C 规范，展示数量以及是否截断列表均由用户代理与操作
      系统自行决定。
- [ ] 始终渲染应用内快速操作菜单作为等效入口——根据 W3C 规范，操作系统快捷方式菜单的
      呈现方式完全由用户代理与操作系统自行决定。
- [ ] 不要假设每位访问者都能看到操作系统快捷方式菜单——Can I Use 显示该功能的全球浏览器
      使用量支持率约为 80%。

## 下一步

- [manifest shortcuts 参考](/zh/reference/manifest/shortcuts/) —— 完整的快捷方式对象语法
  与各平台展示数量限制。
- [manifest: shortcuts 支持情况](/zh/compatibility/manifest-shortcuts/) —— 该 manifest
  成员的按浏览器兼容性数据。