# Badging API：已安装 PWA 的应用图标徽标

> 如何使用 Badging API 在 PWA 的应用图标上设置和清除数字或存在性徽标，以及 Android、iOS 和桌面端的平台支持说明。

**一句话：** Badging API（`navigator.setAppBadge` / `navigator.clearAppBadge`）
让已安装的 PWA 可以在其主屏幕或任务栏图标上显示数字计数或存在性圆点——
这正是原生应用多年来所拥有的徽标指示器。

## 基本用法

```js
// 设置数字徽标（例如未读消息数）。
// 具体如何渲染该数字由操作系统决定。
await navigator.setAppBadge(3);

// 有活动但无有意义的计数时，设置存在性徽标（圆点，无数字）。
await navigator.setAppBadge();

// 清除徽标。
await navigator.clearAppBadge();
```

两个方法均返回 Promise。设置徽标不需要权限提示。
此 API 设计为可从 **Service Worker**（适合推送通知场景）或页面脚本中调用。

### 从 Service Worker 调用

```js
// 在 service-worker.js 中——推送到达时更新徽标。
self.addEventListener('push', (event) => {
  const count = event.data?.json()?.unread ?? 0;
  event.waitUntil(
    self.navigator.setAppBadge(count)
  );
});
```

在支持的浏览器中，Service Worker 作用域内可使用 `self.navigator`。
这允许即使应用页面未打开也能更新徽标。

## 各平台支持

### Android

Android 版 Chrome **不支持** Badging API（`navigator.setAppBadge` 未暴露）。
Android 在收到通知时可能会在应用图标上自动显示通知徽标，但这完全由 Android 系统控制，
无法通过 Badging API 以编程方式设置或清除。

### iOS / Safari

iOS 16.4+ 的 Safari 对**已安装到主屏幕的 Web 应用**支持 Badging API。
徽标与通知权限绑定：用户必须先授予通知访问权限，`navigator.setAppBadge` 才会生效。
关键限制：

- PWA **必须已安装**到主屏幕——普通 Safari 标签页中该 API 不可用。
- 用户必须已为该 PWA 授予**通知权限**。
- 推送通知投递时，操作系统会自动更新徽标；在支持的版本中，页面或 Service Worker 中
  显式调用 `navigator.setAppBadge` 同样有效。
- 在非安装上下文的普通 Safari 标签页中，该方法不对外暴露。

### 桌面端（Chrome / Edge）

Windows、macOS、Linux 和 ChromeOS 上的 Chrome 和 Edge 支持已安装 PWA 的 Badging API。
徽标以叠层形式渲染在任务栏或 Dock 图标上，符合操作系统惯例：

- **Windows：** 任务栏图标上的小彩色圆圈。
- **macOS：** Dock 图标上带数字的红点。
- **Linux / ChromeOS：** 平台特定渲染；Chrome 使用圆点。

### Firefox

Firefox 目前在任何平台上均不支持 Badging API。

## 特性检测

```js
if ('setAppBadge' in navigator) {
  // Badging API 可用。
  await navigator.setAppBadge(newCount);
} else {
  // 回退到通知或应用内指示器。
}
```

始终用特性检测进行守卫；在不支持的平台上静默跳过徽标更新，而不是抛出错误。

## 数字渲染规则

浏览器/操作系统有自己的渲染规则：

- 值为 0 时被视为"清除"（等同于 `clearAppBadge()`）。
- 非常大的值会被限制在显示最大值（通常为 99 或 999+）。
- 传入 `Infinity` 或 `NaN` 会清除徽标。
- 徽标数字是一个提示，不是精确显示的保证。

## 隐私注意事项

徽标对能看到设备主屏幕或任务栏的任何人可见。
避免在徽标计数中编码敏感信息（消息内容、账号等）。
通用的未读数量是合适的；个人可识别内容则不然。

## 兼容性

当前浏览器支持数据，请查看 [/compatibility/](/zh/compatibility/)。

## 在线试用

配套演示 [/demo/#badging](/demo/#badging) 用计数器调用 `navigator.setAppBadge()`，并用 `clearAppBadge()` 重置。请先安装演示：在标签页中调用同样会 resolve，但徽标只会绘制在已安装应用的图标上。

## 实践检查清单

- [ ] 调用 API 前进行 `'setAppBadge' in navigator` 特性检测。
- [ ] 从 Service Worker 推送处理程序中调用，以便在页面关闭时更新徽标。
- [ ] 用户打开并阅读相关内容时调用 `clearAppBadge()`。
- [ ] 将徽标更新视为提示；不要依赖精确的数字渲染。
- [ ] iOS 端：确保 PWA 已安装到主屏幕且已授予通知权限，再调用 Badging API（iOS 16.4+）。
- [ ] 为不支持徽标的平台（Android Chrome、Firefox、旧版 iOS）提供应用内未读指示器作为回退。
- [ ] 不在徽标计数中放置敏感内容。