徽章 API

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

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

特殊值 "nothing"：

表示当前没有设置徽章。

特殊值 "flag"：

表示徽章已设置，但不包含特定值。

数字值：

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

已安装的 Web 应用程序具有一个关联的徽章，其被初始化为 "nothing"。

用户代理可以自行决定（重新）设置应用程序的徽章为 "nothing"（例如，遵循系统惯例）。

当应用程序的徽章被设置时，用户代理或操作系统应该将应用程序的徽章与用户操作系统中应用程序的主要图标表示一起显示（例如，作为设备主屏幕上应用程序图标顶部的一个小覆盖层）。

用户代理可以要求用户明确许可才能设置徽章。当用户代理需要此类许可时，它应该将许可授予与“notifications”许可绑定。

当徽章被设置为"flag"时，用户代理或操作系统应该显示一个带有非特定符号的指示器（例如，一个彩色的圆圈）。

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

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

• 应该根据用户的字体和格式偏好来格式化和显示数字。例如，作为设备主屏幕上应用程序图标顶部圆圈中的数字。
• 可以以任何符合平台在徽章中表示数字的惯例的方式，简化或降级徽章的数字值。例如，平台可能会选择将值为 '100' 的徽章显示为 '99+'。
• 应该根据用户的区域设置偏好来本地化数字。例如，值 '7' 在区域设置 'en' (英语) 中应显示为 '7'，但在 'ar' (阿拉伯语) 中应显示为 '٧'。
• 如果平台不支持在徽章中显示数字，可以将数字值视为"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）将速率限制留给操作系统，因为操作系统能更好地根据系统负载、用户偏好和无障碍需求来决定合适的限流策略。

除标记为非规范性的章节外，本规范中的所有编写指南、图示、示例和注释均为非规范性内容。规范其他部分均为规范性内容。

本文档中的关键字可以、必须、应当和不应 按照 BCP 14 [RFC2119] [RFC8174] 的描述进行解释，仅在以此处所示的大写形式出现时适用。