App Badging API 可让已安装的 Web 应用在应用图标上设置应用级徽章。
什么是 App Badging API?
![示例:显示有八条通知的 Twitter 应用,以及显示旗帜类型标志的另一个应用。](https://developer.chrome.google.cn/static/docs/capabilities/web-apis/badging-api/image/example-twitter-eight-n-6eda9c7385a6d.jpg?authuser=6&hl=uk)
App Badging API 允许已安装的 Web 应用设置应用级徽章,该徽章显示在与应用关联的操作系统专用位置(例如任务栏或主屏幕)。
通过标记,您可以轻松以不易察觉的方式通知用户有可能需要用户注意的新 activity,或者指明少量信息,例如未读计数。
徽章往往比通知更方便用户使用,并且更新频率可以高很多,因为它们不会干扰用户。而且,由于它们不会干扰用户,因此无需用户的许可。
可能的用例
可能会使用此 API 的应用示例包括:
- 聊天、电子邮件和社交应用,用于指示收到了新消息,或显示未读内容的数量。
- 效率应用,用于发送信号,表明长时间运行的后台任务(如渲染图片或视频)已完成。
- 游戏,用于指示玩家需要采取行动(例如,在国际象棋中,当轮到玩家时)。
支持
App Badging API 适用于 Windows 和 macOS,以及 Chrome 81 和 Edge 81 或更高版本。 对 ChromeOS 的支持正在开发中,并将在未来版本中提供。Android 不支持 Badging API。而是在有未读通知时,在已安装的 Web 应用图标上自动显示标志,就像 Android 应用一样。
试用
- 打开 App Badging API 演示。
- 出现提示时,点击安装安装该应用,或使用 Chrome 菜单安装该应用。
- 将其作为已安装的 PWA 打开。请注意,它必须作为已安装的 PWA 运行(在任务栏或 Dock 中)。
- 点击 Set 或 Clear 按钮,以设置或清除应用图标中的标记。您还可以为徽章值提供一个数字。
如何使用 App Badging API
如需使用 App Badging API,您的 Web 应用需要符合 Chrome 的可安装性标准,并且用户必须将其添加到自己的主屏幕。
Badge API 包含两个 navigator
方法:
setAppBadge(
number
)
:设置应用的标志。如果提供了值,请将标志设置为提供的值,否则,显示纯白点(或适合平台的其他标志)。将number
设置为0
与调用clearAppBadge()
相同。clearAppBadge()
:移除应用的标志。
两者都返回可用于错误处理的空 promise。
可以在当前页面中设置标志,也可以通过注册的 Service Worker 设置标志。如需设置或清除标记(在前台页面或 Service Worker 中),请调用:
// 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 在后台设置和清除标志
您还可以使用 Service Worker 在后台设置应用标志。您可以通过定期后台同步和/或 Push API 执行此操作。
定期后台同步
借助定期后台同步,Service Worker 可以定期轮询服务器(可用于获取更新的状态),并调用 navigator.setAppBadge()
。
但是,调用同步的频率并非完全可靠,是由浏览器自行决定的。
Web Push API
借助 Push API,服务器可以向 Service Worker 发送消息,即使没有运行前台页面,Service Worker 也可以运行 JavaScript 代码。因此,服务器推送可以通过调用 navigator.setAppBadge()
来更新标志。
不过,大多数浏览器(包括 Chrome)都要求在每次收到推送消息时显示通知。这对于某些用例(例如,在更新标志时显示通知)来说没有问题,但在显示通知的情况下无法微调标志。
此外,用户必须授予您的网站通知权限才能接收推送消息。
结合使用这两者
虽然并不完美,但结合使用 Push API 和定期后台同步是一个很好的解决方案。高优先级信息通过 Push API 传送,显示通知并更新标志。优先级较低的信息可通过更新标志来提供,可以在页面打开时进行更新,也可以通过定期后台同步进行提供。
反馈
Chrome 团队希望了解您使用 App Badging API 的体验。
向我们介绍 API 设计
API 中是否有某些内容无法按预期运行?或者,是否缺少一些方法或属性来实现您的想法? 您对安全模型有疑问或意见吗?
- 在 Badging API GitHub 代码库上提交规范问题,或将您的想法添加到现有问题中。
报告实施方面的问题
您是否发现了 Chrome 实现方面的错误?或者实现方式是否不同于规范?
- 在 https://new.crbug.com 提交 bug。请务必提供尽可能多的详细信息、有关重现的简单说明,并将组件设为
UI>Browser>WebAppInstalls
。Glitch 非常适合用于快速轻松地分享重现的视频。
显示对该 API 的支持
打算在您的网站上使用 App Badging API?您公开提供的支持有助于 Chrome 团队确定功能的优先级,并向其他浏览器供应商显示支持这些功能的重要性。
- 请使用 # 标签
#BadgingAPI
向 @ChromiumDev 发送一条推文,并告诉我们您使用该产品的位置和方式。
实用链接
- 公开解说
- 规范草稿
- Badging API 演示 | Badging API 演示源代码
- 跟踪 bug
- ChromeStatus.com 条目
- Blink 组件:
UI>Browser>WebAppInstalls
主打照片,作者:Prateek Katyal,来源:Unsplash