Badging API

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

安全上下文: 此项功能仅在一些支持的浏览器安全上下文(HTTPS)中可用。

备注: 此特性在 Web Worker 中可用。

Badging API 为 Web 开发人员提供了一种在文档或应用程序上设置徽章的方法,用以充当状态已更改的通知,而不显示更分散注意力的通知。一个常见的用例是具有消息传递功能的应用程序,在应用程序图标上显示徽章以表明新消息已到达。

概念和用法

Web 开发人员经常更新文档图标或标题以指示状态。Badging API 提供了一种更优雅的方式来显示状态,它提供了一种对用户代理有意义的方法,因此可以与 UI 其余部分相匹配的方式显示。

徽章类型

徽章有两种类型:

  • 文档徽章(document badge),通常显示在页面图标附近或页面图标上的浏览器选项卡中。
  • 应用程序徽章(app badge),与已安装的 Web 应用程序的图标相关联。这些可能会显示在扩展坞、工具架或主屏幕的应用程序图标上,具体取决于所使用的设备。

徽章状态

徽章可以具有三个可能值之一,这些值是在内部设置的:

nothing

表示当前未设置徽章。若徽章被应用程序清除或被用户代理重置,徽章可能会处于此状态。

flag

表示已设置徽章,但没有具体数据可显示。如果应用程序已设置徽章,但未将任何值传递给该方法,则徽章将处于此状态。

一个整数

设置徽章时传递的值。该值永远不会是 0,设置徽章时传递值 0 将导致用户代理通过将其设置为 nothing 来清除徽章。

设置徽章

使用 setAppBadge() 方法设置徽章(对于已安装的应用程序)。如果没有参数传递给这些方法,则徽章值为 flag。用户代理将显示其通知标志,例如图标上的彩色圆圈。

这些方法还可以传递一个参数 contents,该参数应该是一个数字。然后,这将显示为徽章的一部分。用户代理可能会以某种方式更改此值。例如,如果你传递一个非常大的数字(例如 4000),用户代理可能会在徽章中将其显示为 99+。用户代理也可以忽略此数据并替代地显示标记。

清除徽章

使用 clearAppBadge() 方法清除徽章。这些不带任何参数并将徽章设置为值 nothing。此外,将 0 值传递给 setAppBadge() 会将徽章设置为 nothing 并清除徽章。

接口

无。

在与此应用程序关联的图标上设置徽章。

清除与此应用程序关联的图标上的徽章。

WorkerNavigator 接口的扩展

WorkerNavigator.setAppBadge()

在与此应用程序关联的图标上设置徽章。

WorkerNavigator.clearAppBadge()

清除与此应用程序关联的图标上的徽章。

示例

要在当前应用程序上设置值为 12 的通知徽章:

js
navigator.setAppBadge(12);

要清除当前应用程序上的通知标志:

js
navigator.clearAppBadge();

规范

Specification
Badging API
# setappbadge-method

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
setAppBadge

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
See implementation notes.

参见