跳转到内容

安装中的 API

Badging API

发布于 更新于

有限可用不支持的浏览器: Chrome (Android)、Firefox (Desktop)、Firefox (Android)W3C 草案

Badging API 可以在已安装 web 应用的任务栏、Dock 或主屏幕图标上显示数字或圆点。页面调用 navigator.setAppBadge() 和 navigator.clearAppBadge(),service worker 内的 WorkerNavigator 也提供这两个方法。Chrome 81 与 Edge 81 在 Windows 与 macOS 上绘制它,ChromeOS 上自 Chrome 91 起;Safari 16.4 为 iOS 主屏幕 web 应用绘制,Safari 17 为 macOS Sonoma 及更高版本上的 Dock web 应用绘制;browser-compat-data 没有记录 Android 版 Chrome、Samsung Internet 或 Android WebView 的支持,Firefox 也没有实现(BCD api.Navigator.setAppBadge)。

await navigator.setAppBadge(); // 一个圆点("flag"),不带数字
await navigator.setAppBadge(contents); // 一个数字;0 表示清除
await navigator.clearAppBadge(); // 移除角标
// service worker 内,例如在 push 处理器中
self.navigator.setAppBadge(count);

两个方法都返回 Promise<void>,在请求交给操作系统后兑现,而不是在角标可见时。Chromium 上不涉及权限提示;iOS 上只有用户允许了已安装应用的通知之后才会绘制角标。

只有 setAppBadge() 接受参数。

名称 类型 说明
contents unsigned long long,可选 要显示的数字。0 清除角标,等同于 clearAppBadge()。省略时角标被设为“flag”状态,规范要求平台以不带数字的标记显示,例如一个彩色圆点;平台不支持 flag 时,以最接近的形式显示,例如“1”。大数字如何显示由操作系统决定;规范把该值称为提示,允许平台缩写。

setAppBadge() 在四种情形下拒绝;在另外两种情形下不报错地兑现,但看不到角标。

  • TypeError:contents 无法按 [EnforceRange] unsigned long long 转换,即 NaN、无穷大,或向零截断后仍为负数或大于 2^53 − 1 的值(Web IDL 先截断,所以 3.5 设为 3,-0.5 设为 0)。该方法返回 Promise,Web IDL 规定返回 Promise 的操作在参数转换出错时返回被拒绝的 Promise,而不是同步抛出。
  • InvalidStateError:调用方文档不处于 fully active 状态(例如已脱离文档的 iframe),这是规范中两个方法的第一步。
  • SecurityError:调用方文档的源与顶层源不是 same origin-domain,例如跨源 iframe。
  • NotAllowedError:浏览器要求通知权限才能设置角标,而权限不是 granted。规范允许这样做;WebKit 不这样做(见下一种情形)。
  • 应用未安装时,调用不报错,也不显示角标。Chrome 的角标指南说该 API 需要已安装的应用,并建议只要 API 存在就调用、不必看安装状态;未安装的站点调用时不会绘制角标。
  • iOS 16.4 及以后的主屏幕 web 应用尚未获准通知时,调用不报错,也不显示角标。WebKit 的 16.4 文章说,两个方法“甚至在获得显示计数的权限之前”就会改变计数,用户允许通知后图标立即显示当前计数。

Firefox 中 navigator.setAppBadge 为 undefined,未加保护的调用在触及 API 之前就会抛出 TypeError。

可以在 service worker 或页面中更新角标。浏览器没有这项 API 时,需要提供回退。

把 push 事件里的未读数同步到图标

链接到“把 push 事件里的未读数同步到图标”一节

推送载荷若携带服务端的未读数,可以在用户打开应用之前就更新图标。event.waitUntil() 让 worker 存活到角标调用落定;在页面显示收件箱、用户已看过未读项时调用 clearAppBadge(),可以去掉不再需要的角标。

sw.js
self.addEventListener('push', (event) => {
const data = event.data?.json() ?? {};
const unread = Number.isInteger(data.unread) ? data.unread : 0;
event.waitUntil(Promise.all([
self.registration.showNotification(data.title ?? 'New message'),
self.navigator.setAppBadge(unread),
]));
});
// page.js,在显示收件箱视图时
navigator.clearAppBadge?.();

Chrome 的角标指南说,包括 Chrome 在内的大多数浏览器要求收到推送消息时显示通知,所以 push 处理器无法悄悄更新角标;WebKit 更进一步,会撤销 push 事件不显示通知的订阅(WebKit,“Meet Web Push”)。因此上面的通知调用不可省略。若要不打扰地更新角标,Chrome 的指南建议在页面打开时更新,或通过 Periodic Background Sync 更新。

缺少 setAppBadge 时,标签页标题是每个浏览器都有的界面;MDN 提到网站一直用标题或 favicon 表示状态。回退代码把计数加在标题开头,计数为零时去掉前缀。

function showUnread(count) {
if ('setAppBadge' in navigator) {
return count > 0 ? navigator.setAppBadge(count) : navigator.clearAppBadge();
}
// 没有 Badging API(例如 Firefox):改用标题。Chromium 对未安装的站点也提供该 API,只是不绘制。
const base = document.title.replace(/^\(\d+\) /, '');
document.title = count > 0 ? `(${count}) ${base}` : base;
return Promise.resolve();
}

Firefox 用户可以在标签页打开期间从标题看到计数。Badging API 没有这一限制。

规范

规范状态
Badging API(角标)W3C 草案
  • 图例
  • 支持
  • 部分支持
  • 需开启标志
  • 不支持
  • 未知
浏览器 / 平台支持版本置信度来源备注
Chrome (Desktop)#支持81高来源123
Chrome (Android)#不支持—高来源4
Edge (Desktop)#支持81高来源5678
Firefox (Desktop)#不支持—高来源9
Firefox (Android)#不支持—高来源1011
Safari (macOS)#支持17高来源1213
Safari (iOS)#支持16.4高来源1415
Samsung Internet#不支持—高来源1617
WebView (Android)#不支持—高来源1819
  1. Windows 与 macOS 自 Chrome 81 起支持。
  2. ChromeOS 自 Chrome 91 起支持。
  3. Linux 在操作系统层面没有通用的角标 API。
  4. browser-compat-data 未记录 Chrome Android 的支持。
  5. Windows 与 macOS 自 Chrome 81 起支持。
  6. ChromeOS 自 Chrome 91 起支持。
  7. Linux 在操作系统层面没有通用的角标 API。
  8. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  9. browser-compat-data 未记录 Firefox 的支持。
  10. browser-compat-data 未记录 Firefox for Android 的支持。
  11. 由 browser-compat-data 镜像自 Firefox 的数据推导。
  12. macOS Sonoma 及更高版本上,已安装的 Web 应用支持角标。
  13. 传入 `0` 会清除角标,而不是显示一个不带数字的圆点。
  14. 添加到主屏幕的 Web 应用支持角标。
  15. 传入 `0` 会清除角标,而不是显示一个不带数字的圆点。
  16. browser-compat-data 未记录 Samsung Internet 的支持。
  17. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
  18. browser-compat-data 未记录 WebView Android 的支持。
  19. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。

源数据: /compatibility/badging-api.json · 全球使用占比: 57 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · MDN · 最近核验 2026-10-20 · 置信度: 高 (由来源计算)