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

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

基本用法

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

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

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

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

从 Service Worker 调用

// 在 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。

特性检测

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

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

数字渲染规则

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

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

隐私注意事项

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

兼容性

当前浏览器支持数据，请查看 /compatibility/。

在线试用

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

实践检查清单

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