徽章 API

徽章旨在作为 已安装的 Web 应用程序 向用户通知存在某些需要他们关注的新活动的一种机制，或者用来指示少量信息，例如未读计数。

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

特殊值 "nothing"：

表示当前没有设置任何徽章 设置。

特殊值 "flag"：

表示徽章已设置，但不包含具体值。

数值：

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

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

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

当应用程序的徽章被设置时，用户代理或操作系统应当在用户操作系统中显示应用程序的徽章，通常作为设备主屏幕上应用程序图标上的小覆盖物。

用户代理可以要求用户提供明确的权限来设置徽章。当用户代理要求此类权限时，应当将权限授予绑定到“通知”权限。

当徽章被设置为"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. 令 promise 为 一个新的 promise。
4. 并行执行：
   1. 如果 this 的相关设置对象的来源与 this 的相关设置对象的顶级来源不同，则在 global 上排入一个全局任务于DOM 操作任务源，以拒绝 promise，并带有一个 "SecurityError"，然后终止此算法。
   2. 如果用户代理需要明确的权限来设置应用徽章，则：
      1. 令 permissionState 为通过 "通知" 获取当前权限状态的结果。
      2. 如果 permissionState 不是 "granted"，则在 global 上排入一个全局任务于用户交互任务源，以拒绝 promise，并带有一个 NotAllowedError，然后终止此算法。
   3. 根据 contents 进行切换，如果：

      contents 未被传递：

      设置 badge 为 "flag"。

      contents 为 0：

      设置 badge 为 "nothing"。

      contents：

      设置 badge 为 contents。

   4. 在 global 上排入一个全局任务于DOM 操作任务源，以解析 promise，返回undefined。
5. 返回 promise。

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

用户代理或操作系统可以在其自行决定的情况下清除一个徽章，并遵循任何系统约定（例如，在系统重置时）。

与标记为非规范性的部分一样，本规范中的所有作者指南、图表、示例和注释均为非规范性的。本规范中的其他所有内容均为规范性的。

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