如何借助navigator.setAppBadge让PWA应用在桌面端实现实时业务状态提醒

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”，可手动触发测试