在应用图标上显示徽章

对徽章的支持

应用徽章仅在 PWA 安装到其宿主操作系统后才受支持。徽章会显示在应用图标上，而应用图标只有在应用安装后才会存在。

桌面支持

在桌面操作系统上，徽章仅在 Windows 和 macOS 上受支持，并且仅当 PWA 是从 Chrome 或 Edge 安装时才支持。虽然徽章 API 在 Linux 上的基于 Chromium 的浏览器中受支持，但在该操作系统上不显示徽章。

桌面上的 Safari 和 Firefox 不支持徽章 API，也不支持安装 PWA。

移动支持

从 iPadOS 16.4 开始，Safari 在 iOS 和 iPadOS 上支持徽章。徽章 API 在 Android 上运行的基于 Chromium 的浏览器中不受支持。取而代之的是，当有未读通知时，Android 会像对待 Android 应用一样，自动在 PWA 的应用图标上显示徽章。

徽章最佳实践

在学习如何使用徽章之前，请考虑这些最佳实践，以确保您的应用以最有效和最有用的方式为您的用户使用徽章。

检查支持情况

为确保用户浏览器和操作系统 支持 徽章 API，防止 JavaScript 错误，请在使用 API 前检查支持情况。

if (navigator.setAppBadge) {
  // The API is supported, use it.
} else {
  // The API is not supported, don't use it.
}

不要仅依赖徽章来通知用户新内容可用。支持徽章 API 的浏览器可能安装在不支持显示徽章的操作系统上。例如，虽然 Chrome 支持徽章 API，但在 Linux 上安装的应用图标上不会显示徽章。

请求 iOS 和/或 iPadOS 的通知权限

虽然 iOS 和 iPadOS 支持通知徽章，但在授予应用程序通知权限之前，徽章不会出现。要请求通知权限，请调用 Notification.requestPermission() 方法。

Notification.requestPermission().then((result) => {
  console.log(result);
});

您还可以选择使用 权限 API 检查用户是否之前已授予通知权限。

谨慎使用徽章

与通知一样，徽章可以在谨慎使用时成为重新吸引用户使用您的应用的有效方式。请确保仅使用徽章来指示对您的用户很重要的新内容。

实时更新徽章

确保实时更新您的应用程序徽章。这意味着将徽章计数更新为反映用户实际还有多少新项目可供消费，并在没有新项目时清除应用徽章。

例如，如果电子邮件客户端应用在后台收到新邮件，它应该更新其徽章以显示收件箱中未读邮件的正确数量，可能还会过滤掉其他文件夹（如垃圾邮件文件夹）中的邮件。可以使用服务工作线程中的 navigator.setAppBadge() 方法 在后台更新徽章。

一旦用户启动应用程序并开始阅读邮件，电子邮件客户端应用就应该通过调用带有新未读邮件计数的新 navigator.setAppBadge()，或在没有未读邮件时调用 navigator.clearAppBadge() 来相应地更新其徽章。

在应用中突出显示新内容

当您的应用收到新内容并在应用图标上添加徽章时，请确保在用户启动应用时突出显示该新内容。

例如，如果电子邮件客户端应用在应用图标徽章上显示未读邮件数量，那么当应用打开时，这些邮件应该加粗或以某种方式突出显示。

显示和更新徽章

要显示 PWA 应用图标上的徽章以显示未读邮件数量，请使用 Navigator.setAppBadge() 方法。

// Check for support first.
if (navigator.setAppBadge) {
  // Display the number of unread messages.
  navigator.setAppBadge(numberOfUnreadMessages);
}

您也可以通过省略计数参数或将其设置为 0 来使用相同的方法显示一个空的徽章。

// Check for support first.
if (navigator.setAppBadge) {
  // Just display the badge, with no number in it.
  navigator.setAppBadge();
}

要删除应用图标上的徽章，请使用 Navigator.clearAppBadge() 方法。

// Check for support first.
if (navigator.clearAppBadge) {
  // Remove the badge on the app icon.
  navigator.clearAppBadge();
}

在后台更新徽章

当用户不使用您的应用时，徽章可以帮助他们重新参与到您的应用中。这意味着您的应用必须能够在未运行时更新其徽章。

PWA 可以使用以下机制在后台更新并显示、更新或隐藏其徽章：

推送 API

PWA 可以使用此 API 在应用未运行时接收来自服务器的消息。大多数浏览器在收到推送消息时都需要显示通知。这对于某些用例（例如，在更新徽章时显示通知）是可以的，但使得在不显示通知的情况下微妙地更新徽章成为不可能。此外，用户必须授予您的网站通知权限才能接收推送消息。有关更多信息，请参阅 ServiceWorkerRegistration: showNotification() 方法。

Background Synchronization API

PWA 可以使用此 API 在检测到稳定的网络连接时在后台运行代码。

Web Periodic Background Synchronization API

PWA 可以使用此 API 在预定的时间间隔内运行代码。

这是一个服务工作线程代码示例，展示了如何监听服务器的推送消息并更新应用徽章以反映未读邮件数量。

// Listen to "push" events in the service worker.
self.addEventListener("push", (event) => {
  // Extract the unread count from the push message data.
  const message = event.data.json();
  const unreadCount = message.unreadCount;

  // Set or clear the badge.
  if (navigator.setAppBadge) {
    if (unreadCount && unreadCount > 0) {
      navigator.setAppBadge(unreadCount);
    } else {
      navigator.clearAppBadge();
    }
  }
  // It's obligatory to show the notification to the user.
  self.registration.showNotification(`${unreadCount} unread messages`);
});

另见

• 如何创建应用徽章
• 应用图标的徽章
• 使用徽章、通知和推送消息重新吸引用户
• 编码实验：构建一个推送通知服务器