> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 徽章
> 管理 iOS、Android 和华为上推送通知的应用图标徽章计数，包括自动清除、API 控制和原生徽章逻辑。
徽章是出现在您的移动应用图标上的小数字点。它们有助于吸引用户注意力并可以影响参与行为。特别是在 iOS 上，徽章需要额外的设置并提供灵活的控制，如下所述。
对于 Android Web 推送通知，徽章是指显示在通知上的小图标——而不是应用图标——并且可以自定义。请参阅 [Web 推送徽章](./push#badges)。
***
## Android 徽章
Android 应用图标徽章行为可以通过 [Android 通知类别](./android-notification-categories) 来管理。您可以控制某个类别（通道）是否显示徽章，并在每个类别的基础上设置徽章行为。
***
## 华为徽章
在华为设备上，徽章可以在应用图标上显示为数字或圆点，具体取决于用户的设备设置。徽章有助于指示未读消息或待处理操作，鼓励用户打开应用。OneSignal 允许您通过仪表板或 API 直接控制华为徽章计数。
### 华为徽章的工作原理
徽章在应用图标上显示为**数字计数**或**圆点**，具体取决于用户的设备设置（**设置 > 通知 > 应用图标徽章**）。您的 API 调用控制底层计数；设备决定视觉样式。
#### 参数
| 参数 | 类型 | 范围 | 描述 |
| ---------------------- | ------- | ---- | --------------------------------------------------------------------------------------- |
| `huawei_badge_class` | string | — | **（必需）** 您应用启动器 Activity 的完全限定类名（例如，`com.example.myapp.MainActivity`）。告知华为系统要显示徽章的应用图标。 |
| `huawei_badge_set_num` | integer | 0–99 | 将徽章设置为精确数字。`0` 清除徽章。 |
| `huawei_badge_add_num` | integer | 1–99 | 将现有徽章计数增加此数量。 |
#### 行为规则
* `huawei_badge_class` 对于任何徽章操作都是必需的。
* 如果同时提供 `huawei_badge_set_num` 和 `huawei_badge_add_num`，`huawei_badge_set_num` 优先。
* 如果两者都未提供（但已设置 `huawei_badge_class`），徽章计数默认增加 1。
### 发送带徽章的华为推送
1. 转到 **消息 > 推送** 或 **模板**
2. 在 **平台设置 > 发送到华为 Android > 徽章** 下
3. 选择以下任一选项：
* **不设置** — 此通知不影响徽章
* **设置为** — 将徽章设置为特定数字（0-99）
* **增加** — 增加现有徽章计数（1-99）
在 [创建消息](/reference/create-message) API 中使用以下参数：
* `huawei_badge_class` — *（字符串，徽章必需）* 应用启动器 Activity 的完全限定类名（例如，`"com.example.myapp.MainActivity"`）
* `huawei_badge_set_num` — *（整数，0-99）* 将徽章计数设置为此精确数字。设置为 `0` 可清除徽章。
* `huawei_badge_add_num` — *（整数，1-99）* 将现有徽章计数增加此数字。如果与 `huawei_badge_set_num` 一起省略，默认增加 1。
**将徽章设置为特定数字：**
```json theme={null}
{
"huawei_badge_class": "com.example.myapp.MainActivity",
"huawei_badge_set_num": 5
}
```
**按特定数量增加徽章：**
```json theme={null}
{
"huawei_badge_class": "com.example.myapp.MainActivity",
"huawei_badge_add_num": 1
}
```
**清除徽章：**
```json theme={null}
{
"huawei_badge_class": "com.example.myapp.MainActivity",
"huawei_badge_set_num": 0
}
```
### 清除徽章
华为**不会**在用户打开应用或点击通知时自动清除徽章。要清除徽章，您有两个选项：
* **通过 API 或仪表板**：发送 `huawei_badge_set_num` 设置为 `0` 的通知（或在仪表板中使用 **设置为 > 0**）。如果您不想显示可见通知，可以使用[数据/后台通知](./data-notifications)。
* **通过客户端代码**：您的应用可以使用华为徽章 API 在本地清除徽章。这需要在您的 `AndroidManifest.xml` 中添加 `com.huawei.android.launcher.permission.CHANGE_BADGE` 权限。有关实现详情，请参阅[华为徽章开发指南](https://developer.huawei.com/consumer/en/doc/hmscore-guides/android-badging-0000001050042083)。
`huawei_badge_set_num` 参数需要 EMUI 10.0.0 或更高版本以及 Push SDK 10.1.0 或更高版本。在较旧的设备上，仅支持 `huawei_badge_add_num`。
***
## iOS 徽章
要确保徽章计数在 iOS 上正确递增，您必须配置：
* `OneSignalNotificationServiceExtension`
* 应用组（App Groups）
请参阅 [移动 SDK 设置](./mobile-sdk-setup) 获取完整说明。
默认情况下，OneSignal SDK 将：
1. 在应用打开时清除应用图标徽章。
2. 从通知中心移除通知。
如果您想保留通知并手动管理徽章逻辑（例如，使用您自己的计数器或在设备间同步状态），您可以禁用此自动行为。
**手动徽章控制的常见用例**
* 在应用启动或恢复时重置徽章
* 在前台接收通知时递增徽章
* 在消息被阅读或关闭时递减
* 通过应用组或您的后端在设备或应用扩展间同步徽章状态
### 禁用自动通知和徽章清除
在您的应用的 `info.plist` 中，添加键：`OneSignal_disable_badge_clearing`，布尔类型，值为 `YES`
```xml theme={null}
OneSignal_disable_badge_clearing
```
这可以防止 SDK 在应用打开时自动移除通知或重置徽章。
#### iOS 原生徽章管理
如果您禁用 OneSignal 的自动徽章清除，您可以使用 Apple 的原生 API 来控制徽章行为。
Apple 在 iOS 17 中弃用了 `UIApplication.shared.applicationIconBadgeNumber`。您现在应该使用来自 [UserNotifications 框架](https://developer.apple.com/documentation/UserNotifications/UNUserNotificationCenter/setBadgeCount\(_:withCompletionHandler:\)) 的以下方法：
**设置徽章计数**
要将应用图标上的徽章设置为特定值：
```swift theme={null}
import UserNotifications
import UIKit
if #available(iOS 17.0, *) {
UNUserNotificationCenter.current().setBadgeCount(5) { error in
if let error = error {
print("Failed to set badge count: \(error.localizedDescription)")
} else {
print("Badge count updated successfully.")
}
}
} else {
UIApplication.shared.applicationIconBadgeNumber = 5
}
```
**获取当前徽章计数**
iOS 不提供从系统检索当前徽章计数的方法。您必须在应用的状态中跟踪徽章计数（例如，使用 `UserDefaults`、应用的数据模型或与后端同步）。
```swift theme={null}
// Example: Store and retrieve badge count using UserDefaults
let badgeCount = UserDefaults.standard.integer(forKey: "badgeCount")
// Update badge count as needed
UserDefaults.standard.set(badgeCount, forKey: "badgeCount")
```
**递增或递减徽章**
您必须手动管理徽章逻辑，因为载荷中不支持相对变化（如 +1 或 -1）。更新您存储的徽章计数然后设置它：
```swift theme={null}
// Example: Increment badge count and update system badge
let currentCount = UserDefaults.standard.integer(forKey: "badgeCount")
let updatedCount = max(0, currentCount + 1)
UserDefaults.standard.set(updatedCount, forKey: "badgeCount")
if #available(iOS 17.0, *) {
UNUserNotificationCenter.current().setBadgeCount(updatedCount)
} else {
UIApplication.shared.applicationIconBadgeNumber = updatedCount
}
```
**清除徽章**
要完全移除徽章：
```swift theme={null}
if #available(iOS 17.0, *) {
UNUserNotificationCenter.current().setBadgeCount(0)
} else {
UIApplication.shared.applicationIconBadgeNumber = 0
}
```
### 发送带有徽章的 iOS 推送
您可以在 OneSignal 控制面板中或使用 API 设置徽章计数。
1. 转到 **消息 > 推送** 或 **模板**。
2. 在 **平台设置 > 发送到 Apple iOS > 徽章** 下。
3. 选择任一选项：
* 设置为特定数字。
* 按相对数量增加。
在 [创建消息](/reference/create-message) API 中使用以下参数：
* `ios_badgeType` — 设置为 `SetTo` 或 `Increase`。
* `ios_badgeCount` — 要设置或增加的数字。
```json theme={null}
{
"ios_badgeType": "Increase",
"ios_badgeCount": 1
}
```
发送 iOS 推送通知时，徽章计数会根据这些选项进行更改。
如果应用是打开的，除非您[禁用自动徽章清除](#disable-automatic-notification-and-badge-clearing)，否则徽章计数将重置。
***
## 常见问题
### 为什么 iOS 上的徽章计数没有递增？
确保您已配置 `OneSignalNotificationServiceExtension` 和应用组（App Groups）。没有这些，徽章计数无法正确递增。请参阅 [移动 SDK 设置](./mobile-sdk-setup) 获取完整说明。
### 如何清除华为上的徽章？
发送 `huawei_badge_set_num` 设置为 `0` 的通知，或在仪表板中使用 **设置为 > 0**。您也可以使用[数据/后台通知](./data-notifications)在不显示可见通知的情况下清除徽章。或者，使用华为徽章 API 在客户端清除徽章。
### 我可以为 Web 推送设置徽章吗？
不可以。应用图标徽章仅在 iOS、Android 和华为上受支持。对于 Android Web 推送，"徽章"是指通知本身上显示的小图标——请参阅 [Web 推送徽章](./push#badges)。
***
## 相关页面
在 Android 上按通知渠道控制徽章显示和行为。
使用 OneSignal 设置华为推送消息。
推送通知功能的完整参考，包括 Web 推送徽章。
配置 OneSignal SDK，包括 iOS 的徽章先决条件。