徽章 API

徽章旨在作为一种机制，供已安装的 Web 应用程序通知用户有某些可能需要他们注意的新活动，或作为指示少量信息（例如未读计数）的一种方式。

一个徽章可以具有以下值之一：

特殊值 "nothing"：

表示当前没有设置徽章。当 徽章为此值时，用户不会看到任何视觉指示器。

特殊值 "flag"：

表示徽章已设置且应展示给用户，但不包含具体数值。与 "nothing"不同，用户会看到徽章存在的视觉指示器。

number值：

表示徽章已设置为大于0的数值。

已安装的网页应用有一个关联的徽章，初始值为"nothing"。操作系统负责存储和管理徽章值，用户代理则作为中介，将徽章的变化通知给操作系统。

用户代理可以根据自身决定（例如遵循系统规范）(重新)设置应用的徽章为 "nothing"。

当应用的徽章被设置时，用户代理或操作系统应该 在用户操作系统中应用的主要图标展示旁，显示该应用的徽章（例如，在设备主屏幕上的应用图标上方以小型覆盖方式展示）。

用户代理可以要求用户明确授权来 设置徽章。当用户代理需要此类 权限时，应该将授权与 "通知"权限绑定。

当徽章被设置为"flag"时，用户代理或操作系统应该显示一个非特定符号的指示器（例如，一个彩色圆圈）。如果平台不支持展示"flag"徽章，用户代理应该使用最接近的可用方式显示徽章以表示徽章存在（例如显示值“1”），而不是完全清除徽章。

当徽章的值被设置为"nothing"时， 用户代理或操作系统应该 清除 徽章，即不再显示该徽章。

当徽章被设置为数字时，用户代理或操作系统：

• 应该根据用户的字体和格式偏好格式化并显示该数字。例如，在设备主屏幕的应用图标上以圆圈内数字的方式展示。
• 可以根据平台对徽章数字表示的规范，以任何方式简化或降级徽章的数字值。例如，平台可能将值为“100”的徽章显示为“99+”。
• 应该根据用户的语言区域偏好本地化显示数字。例如，值“7”应在“en”（英语）环境下显示为“7”，在“ar”（阿拉伯语）环境下显示为“٧”。
• 可以将数字值视为"flag"，或根据平台采用更合适的表示方式，如果平台不支持在徽章中显示数字。同样，如果平台不支持"flag"徽章，则可以使用数字或其他合适的视觉指示器来表示"flag"，但不得清除徽章，当请求"flag"时。

WebIDL[SecureContext]
interface mixin NavigatorBadge {
  Promise<undefined> setAppBadge(
    optional [EnforceRange] unsigned long long contents
  );
  Promise<undefined> clearAppBadge();
};

Navigator includes NavigatorBadge;
WorkerNavigator includes NavigatorBadge;

永不显示应用徽章的用户代理不应 包含NavigatorBadge。

要将平台对象context的应用徽章设置为可选的unsigned long long contents值：

1. 令global为context的相关全局对象。
2. 如果global是Window 对象，则：
   1. 令document为global的关联Document。
   2. 如果document不是完全激活状态，则返回一个被拒绝的 promise，错误为"InvalidStateError" DOMException。
   3. 如果document的相关设置对象的origin与this的相关设置对象的顶级 origin不是同源域，则返回一个被拒绝的 promise，错误为"SecurityError" DOMException。
3. 令promise为一个新的 promise。
4. 并行执行：
   1. 如果用户代理要求明确授权才能设置应用徽章，则：
      1. 令permissionState为使用"notifications"获取当前权限状态的结果。
      2. 如果permissionState不是"granted"， 在global上队列一个全局任务，任务源为用户交互任务源， 以rejectpromise，错误为NotAllowedError 并终止此算法。
   2. 根据contents的情况分支：

      未传递contents：

      设置badge为"flag"。

      contents为0：

      设置badge为"nothing"。

      contents：

      设置badge为contents。

   3. 在global上队列一个全局任务，任务源为DOM 操作任务源 ，以resolvepromise，值为undefined。
5. 返回promise。

该 API 设计为只写。站点无法读取之前设置的徽章值，以确保应用徽章不能被用作存储或指纹识别机制。

用户代理或操作系统可以根据自身决定清除徽章 ，并遵循任何系统惯例（例如系统重置时）。

用户代理 可以（MAY） 对徽章设置 或清除进行速率限制，以防止产生干扰性动画并减少资源使用。然而，用户代理 通常应当（SHOULD）将速率限制留给操作系统，因为操作系统能更好地根据系统负载、用户偏好和无障碍需求来决定合适的限流策略。

应用程序徽章传达可能需要用户注意的状态。由于徽章通常显示在网页内容区域之外（例如，在 dock 中的应用图标上），用户代理需要确保这些信息能够通过平台的无障碍功能和用户偏好进行访问和控制。

除了标为非规范性的章节外，本规范中的所有创作指南、图表、示例和注释均为非规范性内容。规范中的其他内容均为规范性内容。

本文件中的关键词 MAY、MUST、MUST NOT、SHOULD 和 SHOULD NOT 应按照 BCP 14 [RFC2119] [RFC8174] 的说明进行解释，仅当这些词以全大写形式出现时，如此处所示。