# ChromeOS 上的 PWA（启动器与置顶栏）

> 已安装的 PWA 如何融入 ChromeOS：启动器与置顶栏条目、角标、Web Share 与 Share Target、文件处理，以及如何对每项能力做特性检测并提供回退。

在 ChromeOS 上，已安装的 PWA 与 Android 应用、Linux 应用一起列在启动器中，可以固定到置顶栏，并通过与 Windows、macOS、Linux 版 Chrome 相同的 manifest 成员和能力 API 接入系统：置顶栏图标上的角标、Web Share 与 Share Target、文件处理、右键快捷方式。

## 工作原理

ChromeOS 运行的就是桌面版 Chrome，所以安装路径和安装后的窗口都是 Chrome 的；ChromeOS 增加的是应用安装后出现在哪里，以及它能接入哪些系统界面（启动器、置顶栏、「打开方式」列表、分享面板）。

### 从 Chrome 安装

Google 的 ChromeOS 开发者文档要求 manifest 提供名称、图标、`start_url` 与 `display` 模式，并有一个处理 `fetch` 且能在离线时提供 `start_url` 的 Service Worker（[Powerful PWAs](https://developers.google.com/chromeos/app-development/learn/powerful-pwas)，developers.google.com）。满足之后，Chromebook 上的 Chrome 提供与其他桌面平台相同的两条路径（英文界面）：符合条件的站点在地址栏右端显示 **Install** 按钮，或者三点 **More** 菜单，然后 **Cast, save, and share**，再 **Install page as app...**（[Chrome 帮助](https://support.google.com/chromebook/answer/9658361)）。用 Google 的原话，安装后的应用会出现在「along-side other installed apps, like in the taskbar, launcher, desktop, and app switcher」；在 ChromeOS 上，taskbar 指的就是置顶栏。

### ChromeOS 上的能力支持

每一项集成都是独立的 manifest 成员或 API，各自按自己的节奏到达 ChromeOS：

- **角标。**已安装应用调用 `navigator.setAppBadge()`，按 chromeos.dev 的描述，会在置顶栏图标上画出「a small circle on the app's home icon」。
- **Web Share 与 Web Share Target。**`navigator.share()` 在任何标签页中都能打开 ChromeOS 分享面板；`share_target` 成员则把已安装应用注册为接收方，接收其他应用分享的链接、文本或文件。chromeos.dev 建议 `action` 页面要能离线工作，这样分享不会因为没有网络而失败。
- **文件处理。**`file_handlers` 成员让已安装应用出现在 ChromeOS 的「Open with…」列表中，对应声明的 MIME 类型与扩展名；Chrome 102 与 Edge 102 在包括 ChromeOS 的桌面平台上提供该成员（[File Handling API](https://developer.chrome.com/docs/capabilities/web-apis/file-handling)，developer.chrome.com）。文件通过 `window.launchQueue` 送达。
- **应用快捷方式。**`shortcuts` 成员填充启动器与置顶栏中图标的右键菜单。
- **稳定身份。**从 Chrome 96 起，manifest 的 `id` 成员独立于 `start_url` 标识应用，同一个源下的两个 PWA 只要 manifest 的 `id` 不同就能共存（chromeos.dev，2022-05-23）。

Google 的页面明确写道，一项在 Windows 或 macOS 版 Chrome 中已稳定的能力，要在 ChromeOS 上达到稳定支持「can sometimes be a multi-year process」，所以关于 ChromeOS 的结论要在 ChromeOS 上验证。

## 示例

角标与文件处理是分别发布的，也要分别检测；一项通过不代表另一项可用。

### 只在有角标的地方给置顶栏图标加角标

检测 `setAppBadge`，而不是假定 ChromeOS 上已安装的应用一定有它。Firefox 没有实现；在 Android 版 Chrome 84 及之后，同样的调用会成功，但角标只对已安装应用显示，且取决于启动器是否支持（本站 `badging-api` 数据集）。

```js
async function setLauncherBadge(count) {
  if (!('setAppBadge' in navigator)) {
    return false; // 这里没有角标界面：改为在应用内显示计数
  }
  if (count > 0) {
    await navigator.setAppBadge(count);
  } else {
    await navigator.clearAppBadge();
  }
  return true;
}
```

函数在什么都没做时返回 `false`，调用方可以在没有该 API 的浏览器里渲染应用内计数器，而不是悄悄丢掉这个信号。

### 从「Open with…」接收文件

`file_handlers` 成员只在应用安装后生效，`launchQueue` 也只存在于实现了该 API 的浏览器中，所以消费者要放在检测之后注册，普通的文件选择器保留为回退：

```js
if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
  window.launchQueue.setConsumer(async (launchParams) => {
    if (!launchParams.files.length) return;
    for (const handle of launchParams.files) {
      const file = await handle.getFile();
      openDocument(file);
    }
  });
} else {
  document.querySelector('#open-file').hidden = false; // <input type="file"> 路径
}
```

`'files' in LaunchParams.prototype` 这个检测是 developer.chrome.com 给出的写法；只写 `'launchQueue' in window` 也会匹配那些把队列用于其他启动类型的浏览器。

## 实测行为

在 Chromebook 上卸载 PWA 是启动器里的操作，其数据复选框的措辞与 Chrome 在 Windows、macOS 上显示的不同。

:::observed
在 ChromeOS（英文界面）上，右键点击启动器中的应用图标会显示 **Uninstall**；确认对话框里有一个标为「Also delete browsing data」的复选框，Chrome 帮助提醒勾选后会清除 Chrome 中该站点的全部数据，下次访问需要重新登录。同一个对话框在 Windows、macOS、Linux 上的复选框标为「Also delete data from Chrome.」（Chrome 帮助，2026-10 读取）。
:::

由于 ChromeOS 上的存储就是浏览器 profile 的存储，这个复选框也会一并删除该源的 Service Worker 注册与 Cache Storage，之后站点会以首次访问的状态加载。

## 另请参阅

- [Powerful PWAs](https://developers.google.com/chromeos/app-development/learn/powerful-pwas)（developers.google.com）
- [Features to take full advantage of PWA installation](https://chromeos.dev/en/posts/features-to-take-full-advantage-of-pwa-installation)（chromeos.dev）
- [File Handling API](https://developer.chrome.com/docs/capabilities/web-apis/file-handling)（developer.chrome.com）
- [Manifest 文件处理程序（file_handlers）](/zh/reference/manifest/file-handlers/)
- [Manifest 快捷方式（shortcuts）](/zh/reference/manifest/shortcuts/)
- [Badging API：已安装 PWA 的应用图标徽标](/zh/reference/installation/badging/)
- [Chrome 与 Android 上的 PWA](/zh/reference/platforms/chrome-android/)
- [桌面上的 PWA](/zh/reference/platforms/desktop/)