应用图标的标记

借助 App Badging API,已安装的 Web 应用可以在应用图标上设置应用级标记。

显示八条通知的 Twitter 示例,以及另一个显示标志类型标记的应用。
显示八条通知的 Twitter 示例和另一个显示旗帜类型标志的应用示例。

借助 App Badging API,已安装的 Web 应用可以设置应用级标记,该标记会显示在与应用关联的操作系统专用位置(例如搁架或主屏幕)。

借助标记,您可以轻松以不易察觉的方式通知用户有可能需要他们注意的新 activity,或指明少量信息(例如未读计数)。

标记往往比通知更人性化,并且能够以更高的频率更新,因为它们不会干扰用户。此外,由于它们不会干扰用户,因此也不需要用户的许可。

可能的用例

可能使用此 API 的应用示例包括:

  • 聊天、电子邮件和社交应用,用于指示收到了新消息或显示未读条目数。
  • 效率应用,用于指示长时间运行的后台任务(例如渲染图片或视频)已完成。
  • 游戏,用于指示需要玩家执行操作(例如,在国际象棋中,当轮到玩家时)。

支持

App Badging API 适用于 Windows 和 macOS 中的 Chrome 81 和 Edge 81 或更高版本。我们正在开发对 ChromeOS 的支持,并将在未来的版本中提供。在 Android 上,不支持 Badging API。相反,当有未读通知时,Android 会自动在已安装 Web 应用的应用图标上显示标志,就像 Android 应用一样。

试试看

  1. 打开 App Badging API 演示
  2. 出现提示时,点击安装安装该应用,或使用 Chrome 菜单安装该应用。
  3. 以已安装的 PWA 的形式打开该应用。请注意,该应用必须作为已安装的 PWA 运行(在任务栏或基座中)。
  4. 点击设置清除按钮,设置或清除应用图标中的标志。您还可以为徽章值提供一个数字。

如何使用 App Badging API

如需使用 App Badging API,您的 Web 应用需要符合 Chrome 的可安装性标准,并且用户必须将其添加到主屏幕。

Badge API 包含 navigator 上的两个方法:

  • setAppBadge(number):设置应用的徽章。如果提供了值,请将徽章设置为所提供的值;否则,显示一个普通的白色圆点(或适用于平台的其他标志)。将 number 设置为 0 与调用 clearAppBadge() 相同。
  • clearAppBadge():移除应用的标志。

这两者都会返回空 promise,您可以将其用于错误处理。

徽章可以从当前页面或已注册的服务工作器设置。如需设置或清除徽章(在前台页面或服务工件中),请调用以下方法:

// Set the badge
const unreadCount = 24;
navigator.setAppBadge(unreadCount).catch((error) => {
  //Do something with the error.
});

// Clear the badge
navigator.clearAppBadge().catch((error) => {
  // Do something with the error.
});

在某些情况下,操作系统可能不允许准确显示徽章。在这种情况下,浏览器会尝试为该设备提供最佳呈现效果。例如,由于 Android 不支持 Badging API,因此 Android 始终只会显示一个圆点,而不是数字值。

请勿对用户代理如何显示标志做任何假设。某些用户代理可能会将“4000”等数字重写为“99+”。如果您自行饱和徽章(例如将其设置为“99”),则“+”号不会显示。无论实际数字如何,只需调用 setAppBadge(unreadCount),让用户代理相应地处理显示即可。

虽然 Chrome 中的 App Badging API 需要已安装的应用,但您不应根据安装状态调用 Badging API。只需在存在时调用该 API,因为其他浏览器可能会在其他位置显示徽章。如果能行得通,就行。如果没有,则不会显示。

通过 Service Worker 在后台设置和清除标记

您还可以使用服务工件在后台设置应用标记。您可以通过定期后台同步、Push API 或两者的组合来实现此目的。

定期后台同步

定期后台同步允许服务工件定期轮询服务器,以获取更新后的状态并调用 navigator.setAppBadge()

不过,调用同步的频率并不完全可靠,并且由浏览器自行决定。

Web 推送 API

借助 Push API,服务器可以向服务工作器发送消息,即使没有任何前台页面在运行,服务工作器也可以运行 JavaScript 代码。因此,服务器推送可以通过调用 navigator.setAppBadge() 来更新徽章。

不过,大多数浏览器(包括 Chrome)都要求在收到推送消息时显示通知。这对于某些用例(例如在更新徽章时显示通知)来说是可以接受的,但无法在不显示通知的情况下巧妙地更新徽章。

此外,用户必须向您的网站授予通知权限,才能接收推送消息。

结合使用这两者

虽然不完美,但将 Push API 和定期后台同步结合使用是一个不错的解决方案。系统会通过 Push API 传送高优先级信息,以显示通知并更新标记。系统会在网页打开时或通过定期后台同步更新标记,以传达优先级较低的信息。

反馈

Chrome 团队希望了解您使用 App Badging API 的体验。

请向我们说明 API 设计

API 中是否有某些功能未按预期运行?或者,您是否缺少实现想法所需的方法或属性?您对安全模型是否有疑问或意见?

报告实现存在的问题

您是否发现了 Chrome 实现中的 bug?还是实现与规范不同?

  • 请前往 https://new.crbug.com 提交 bug。请务必提供尽可能详细的信息、简单的重现说明,并将组件设置为 UI>Browser>WebAppInstalls故障非常适合分享快速轻松的再现内容。

表示对 API 的支持

计划在您的网站上使用 App Badging API?您的公开支持有助于 Chrome 团队确定功能的优先级,并向其他浏览器供应商表明支持这些功能非常重要。

实用链接

Unsplash 用户 Prateek Katyal 提供的英雄照片