navigator.setAppBadge 是用于在桌面端 PWA 应用图标上显示未读数等状态的 API，仅 Chrome 89+/Edge 91+ 支持，需 PWA 已安装、manifest 设置 display: "standalone" 或 "minimal-ui"、运行于 HTTPS 且用户已授通知权限；调用 navigator.setAppBadge(5) 显示数字，navigator.setAppBadge() 清除，角标仅在应用非聚焦时可见，不支持自定义样式。
navigator.setAppBadge 是 Web App Manifest 规范中用于在桌面端（Windows、macOS、Chrome OS）为 PWA 添加应用角标（App Badge）的 API，可直观显示未读消息数、待处理任务量等实时业务状态。但它有明确的兼容性与使用限制，需配合 manifest 和用户授权谨慎使用。
一、前提条件：确保环境支持且已正确配置
该 API 并非所有浏览器都支持，目前仅 Chrome 89+（桌面端）、Edge 91+ 原生支持，Firefox 和 Safari 尚未实现。同时必须满足以下条件：
- PWA 已通过
beforeinstallprompt安装到桌面（即“添加到主屏幕”或系统级安装） - Web App Manifest 中包含
display: "standalone"或"minimal-ui" - 页面运行在 HTTPS 环境下（localhost 也允许）
- 用户已授予通知权限（
Notification.permission === "granted"），这是调用setAppBadge的强制前提
二、基础用法：设置/清除角标数字
API 接口简单，但行为有约定：
-
navigator.setAppBadge(5)→ 显示角标 “5”（上限为 99，超过自动显示 “99+”） -
navigator.setAppBadge()→ 清除角标（传空参数或不传） - 不支持自定义样式、颜色或图标，仅显示纯数字（系统级统一渲染）
示例：监听 WebSocket 消息后更新未读工单数
if ('setAppBadge' in navigator) {
const unreadCount = await fetchUnreadTickets();
if (Notification.permission === 'granted') {
if (unreadCount > 0) {
navigator.setAppBadge(unreadCount);
} else {
navigator.setAppBadge(); // 清除
}
}
}
三、关键注意事项与常见问题
该 API 行为受系统和浏览器策略约束，容易踩坑：
- 角标仅在应用未聚焦（窗口最小化、切换到其他应用）时可见；当前激活窗口中不会显示
- 部分 Windows 版本（如 Win10 20H2 及更早）可能不显示，推荐测试 Win11 + Chrome 115+
- 无法在 iOS/iPadOS 上使用（Safari 不支持，iOS PWA 本身无角标机制）
- 调用失败时静默失败（不抛异常），建议用
canSetAppBadge预检（Chrome 123+ 支持）
增强健壮性的写法：
async function updateAppBadge(count) {
if (!('setAppBadge' in navigator)) return;
if (Notification.permission !== 'granted') return;
// Chrome 123+ 可选预检
if ('canSetAppBadge' in navigator && !(await navigator.canSetAppBadge())) return;
try {
if (count > 0) {
navigator.setAppBadge(count);
} else {
navigator.setAppBadge();
}
} catch (e) {
// 实际极少抛错，但保留兜底
console.warn('Failed to set app badge', e);
}
}
四、结合业务场景的实用建议
角标适合轻量、高优先级的状态同步，避免滥用：
- ✅ 推荐场景：客服系统未读会话数、审批流待办数量、订单异常预警（如“3 个超时订单”）
- ❌ 不适用场景：实时刷新的秒级倒计时、日志条数、后台同步进度（角标无动画/过渡，频繁变更体验差）
- ? 最佳实践：搭配桌面通知（
new Notification()）使用——角标唤起注意，通知提供详情 - ? 调试技巧：Chrome DevTools → Application → Manifest 标签页底部点击 “Show app badge”，可手动触发测试
