更新记录

1.0.0（2026-02-03）

• 新增：setBadgeCount / clearBadge / getSupportStatus
• Android：厂商 best-effort（小米/华为/OPPO/vivo），默认不发通知
• Android：当 vendor 未识别时，strategy=auto 返回 9002003（提示）或 9002102（桌面解析失败）便于诊断
• Android：新增 9002999 作为兜底异常错误码（debug=true 时 errMsg 会包含更多信息）
• iOS：设置 applicationIconBadgeNumber
• Harmony：best-effort 调用 notificationManager.setBadgeNumber（可能受设备/桌面限制；需开启通知）

平台兼容性

uni-app(4.87)

uni-app x(4.87)

hans-badge-setter

用于设置 App 桌面图标角标（badge） 的 uni-app x UTS 插件。

安装与引入

1) 通过插件市场安装后，项目根目录会出现 uni_modules/hans-badge-setter/

2) 在 uni-app x（.uvue / UTS） 中直接引入：

import { setBadgeCount, clearBadge, getSupportStatus } from '@/uni_modules/hans-badge-setter'

仅支持 App-Android / App-iOS / App-Harmony。若你的项目同时编译到 web/mp，请务必使用条件编译（见下方「多端项目注意」）。

平台支持

• iOS：支持（设置 applicationIconBadgeNumber）
• Android：主流厂商 best-effort（小米 / 华为(含荣耀) / OPPO / vivo）。默认不发通知；允许部分机型/系统版本失败但不崩溃并返回明确错误码
• Harmony：best-effort（默认调用 notificationManager.setBadgeNumber；不同设备/桌面可能表现不一致，部分机型可能直接不支持/需要开启通知权限与桌面角标）

多端项目注意（重要）

本插件仅支持 App-Android / App-iOS / App-Harmony；已移除 utssdk/index.uts 跨平台兜底实现，编译到 web/mp 等平台会因缺少实现而失败。

如果你的项目是「一套代码多端发布」，推荐用条件编译包裹 import 与调用：

// badge.uts（示例：业务侧封装一层，避免非 App 平台编译失败）

// #ifdef APP-ANDROID || APP-IOS || APP-HARMONY
import { setBadgeCount as _setBadgeCount, clearBadge as _clearBadge } from '@/uni_modules/hans-badge-setter'
// #endif

export function setAppBadge(count : number) : void {
  // #ifdef APP-ANDROID || APP-IOS || APP-HARMONY
  _setBadgeCount({ count })
  // #endif
}

export function clearAppBadge() : void {
  // #ifdef APP-ANDROID || APP-IOS || APP-HARMONY
  _clearBadge()
  // #endif
}

使用示例（uni-app x / uvue）

import { setBadgeCount, clearBadge, getSupportStatus } from '@/uni_modules/hans-badge-setter'

const status = getSupportStatus()
console.log('badge support', status)

setBadgeCount({
  count: 12,
  android: { strategy: 'auto', debug: true },
  success: (res) => console.log('success', res),
  fail: (err) => console.log('fail', err),
})

clearBadge({
  android: { strategy: 'auto', debug: true },
  success: (res) => console.log('cleared', res),
  fail: (err) => console.log('fail', err),
})

API

setBadgeCount(options)

函数签名（简化）：

setBadgeCount(options: {
  count: number
  android?: { strategy?: 'auto' | 'vendorOnly' | 'notification', debug?: boolean }
  harmony?: { strategy?: 'badgeNumber' | 'notification', debug?: boolean }
  success?: (res) => void
  fail?: (err) => void
  complete?: (resOrErr) => void
}): void

• count: 角标数字（>= 0）
• android.strategy：
  • auto（默认）：按厂商/桌面路由并自动尝试备选路径
  • vendorOnly：只走厂商路径，失败直接返回对应错误码（便于定位）
  • notification：通过发送一条低等级通知驱动角标（更贴近 Android 生态，vivo 等机型更可能生效；可能在通知栏/通知中心看到一条通知，count=0 会取消通知）
• android.debug: 输出调试日志（console.log）
• harmony.strategy：
  • badgeNumber（默认）：调用 notificationManager.setBadgeNumber(count)（部分桌面可能忽略）
  • notification：额外 publish 一条低等级通知并带上 badgeNumber，用于提升部分机型/桌面显示角标的概率（可能会在通知中心看到一条通知）
• harmony.debug: 输出调试日志（console.log）

clearBadge(options?)

等价于 setBadgeCount({ count: 0, ... })。

getSupportStatus()

返回 { supported, vendorHint, launcherHint }，用于灰度/机型回归/线上定位。

其中：

• supported 可能为 yes | partial | no | unknown（仅供 UI/灰度/日志参考，不代表最终一定显示角标）
• vendorHint Android 会尝试识别 xiaomi/huawei/oppo/vivo/unknown
• launcherHint Android 会返回当前桌面包名（用于定位桌面差异）；Harmony 会包含通知开关提示

Android 说明（重要）

Android 的角标能力由 系统/桌面(Launcher) 决定，不同厂商/系统版本差异很大；本插件在不创建静默通知的前提下只做 best-effort。

尤其是 vivo（com.bbk.launcher2 等）：很多系统版本的角标与“未读通知数”强绑定，或会直接忽略第三方广播更新角标；如果你发现 success 回调触发但桌面无角标，请优先检查：

• 系统设置里该 App 的 通知权限 是否开启（Android 13+ 还需要 POST_NOTIFICATIONS 运行时授权）
• vivo 系统的 桌面角标/应用角标 开关是否开启
• 该桌面是否本身支持数字角标（有的桌面只显示小红点/不显示数字）

当你使用 android.strategy='notification' 时：

• Android 13+：请确保已获取通知运行时权限（否则通知可能无法弹出，进而角标也可能不更新）
• 该策略会创建 hans_badge_setter 通知渠道并发送一条低等级通知（部分 ROM 仍可能显示在通知中心）

建议在业务层：

• 先调用 getSupportStatus() 决定是否展示“角标开关”
• fail 时记录 errCode/vendor/launcher/strategyUsed，便于快速定位机型差异

iOS 说明

• iOS 通过 UIApplication.shared.applicationIconBadgeNumber 设置角标。
• 若用户在系统设置中关闭了该 App 的通知/角标能力，可能出现「调用成功但不显示」；建议引导用户到系统设置开启。

Harmony 说明

• harmony.strategy='badgeNumber'：直接调用 notificationManager.setBadgeNumber(count)（部分桌面可能忽略）
• harmony.strategy='notification'：会额外发布/取消一条通知以提升显示概率
• 若系统通知被禁用，会返回 9004002（请先在系统设置为该 App 开启通知）

错误码（节选）

• 9001001 参数非法（count < 0 或 NaN）
• 9002001 平台不支持
• 9002002 Android 厂商不支持（android.strategy=vendorOnly 且非小米/华为/OPPO/vivo）
• 9002003 Android 可能需要“通知角标/桌面能力”（android.strategy=auto 且无法按厂商路径处理时给出的提示码）
• 9002101 Android 启动 Activity 解析失败（应用安装/Manifest 异常等）
• 9002201 华为角标调用失败
• 9002202/9002203 小米角标调用失败（provider / broadcast）
• 9002204/9002205 OPPO 角标调用失败（provider / broadcast）
• 9002206 vivo 角标调用失败（broadcast）
• 9002301 Android 通知角标调用失败（notification）
• 9002102 Android launcher 解析失败（用于诊断桌面环境异常）
• 9002999 Android 未知错误（兜底异常）
• 9003001 iOS 设置角标失败
• 9004001 Harmony 设置角标失败（可能是能力不支持/通知被禁用/系统限制等；errMsg 会带上系统错误信息）
• 9004002 Harmony 通知被禁用（需要在系统设置里为该 App 打开通知；否则 setBadgeNumber/通知角标都可能无效）

完整错误码定义与回调类型见 utssdk/interface.uts。

常见问题（FAQ）

1) 为什么 success 了但桌面没显示角标？

这是 Android/Harmony 上最常见的情况：角标最终是否显示由系统/桌面决定。

建议按顺序排查：

• 确认系统通知权限已开启（Android 13+ 还需运行时授权；Harmony 若通知禁用会直接返回 9004002）
• 确认桌面/系统的“应用角标/桌面角标”开关已开启
• 在 Android 上尝试 android.strategy='notification'（部分机型更可能生效，但会产生一条低等级通知）

2) 角标数字是否有上限？

不同系统/桌面可能对数值进行截断或改为 99+ / 红点显示；插件不会强制截断，交由系统处理。

开发文档（参考）

• UTS 语法：https://uniapp.dcloud.net.cn/tutorial/syntax-uts.html
• UTS 插件：https://uniapp.dcloud.net.cn/plugin/uts-plugin.html