如何利用 navigator.setAppBadge 实现 PWA 应用在桌面端的实时业务状态提醒
你是否希望自己的 PWA 应用在用户桌面上也能像原生应用一样，通过图标角标清晰展示未读消息或待处理任务的数量？navigator.setAppBadge API 正是实现这一功能的核心技术。它基于 Web App Manifest 标准，专为 Windows、macOS 等桌面操作系统设计，能够为已安装的 PWA 应用添加数字角标，从而高效传递实时业务状态。然而，该功能的使用存在明确的运行环境、配置及用户授权要求，开发者需要全面了解并妥善处理这些前提条件。
一、前提条件：确保环境支持且已正确配置
首先需要明确，此功能并非在所有浏览器和环境中都可用。目前，仅 Chrome 89+（桌面版）和 Edge 91+ 提供了原生支持，Firefox 和 Safari 尚未实现。在开始编码前，请务必确认以下四个核心条件均已满足：
- 应用已安装：PWA 必须已通过“添加到主屏幕”或系统安装流程，成功部署到用户桌面。
- 清单配置正确：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 不支持此 API，且 iOS 系统的 PWA 本身不具备角标机制。
- 静默失败：API 调用失败时通常不会抛出异常，这给调试带来了一定困难。幸运的是，Chrome 123+ 版本提供了一个实验性的
canSetAppBadge方法，可用于预先检测功能是否可用。
因此，一个更健壮、可维护的实现应包含权限检查、能力预检和错误兜底逻辑：
async function updateAppBadge(count) {
// 1. 基础能力检测
if (!('setAppBadge' in navigator)) return;
// 2. 权限检查
if (Notification.permission !== 'granted') return;
// 3. (可选) 高级能力预检，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个超时订单”）。这些场景状态变化频率适中，且信息优先级较高。
- ❌ 不适用场景：实时秒级更新的倒计时、持续增长的日志条目数、后台同步进度百分比。角标缺乏过渡动画，频繁且快速地变化会带来糟糕的用户体验，并削弱其提示意义。
