更新记录
1.0.0(2026-11-18)
- 实现 Android、iOS、HarmonyOS 桌面角标设置与清除
平台兼容性
uni-app(5.25)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| √ | √ | × | × | √ | √ | √ | √ | √ |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| × | × | × | × | × | × | × | × | × | × | × | × |
uni-app x(5.25)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| × | × | √ | √ | √ | × |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | × | × | √ |
yt-badge 桌面应用角标
设置、更新和清除系统桌面上 App 图标的未读角标,提供通知授权、环境检测和打开设置的方法。适用于 Android、iOS、HarmonyOS App,不依赖推送 SDK、远程服务或其它角标插件。
unread 表示绝对未读数:先设置 8,再设置 3,目标数量是 3,不是 11。插件操作的是桌面 App 图标,不是页面内的红点组件;Web、小程序调用会返回 9310002。
Android 最终显示数字、圆点还是不显示,由系统桌面、应用资格和用户设置共同决定。进入 success 不代表桌面已经显示数字。 建议先阅读集成步骤,再根据测试手机查阅品牌设置。
目录
- 1. 支持范围与接入条件
- 2. 集成步骤
- 3. uni-app x 完整调用示例
- 4. 方法与参数详解
- 5. 回调、报告与状态说明
- 6. Android 通用设置与通知机制
- 7. Android 各品牌设置及限制
- 8. iOS 与原生 HarmonyOS 设置
- 9. 业务接入与后台调用
- 10. 错误码与问题排查
- 11. 真机记录与验收建议
1. 支持范围与接入条件
| 项目 | 说明 |
|---|---|
| 插件类型 | uni_modules 形式的 UTS API 插件;通过函数调用,无需注册组件 |
| 开发工具 | 插件声明 HBuilderX 4.61+;已有编译记录使用 HBuilderX 5.26。具体平台还需满足对应 HBuilderX、SDK 和构建环境要求 |
| uni-app x | 页面使用 .uvue / UTS;下方完整示例适用于 Vue3 组合式写法 |
| 普通 uni-app | Vue3 .vue 页面从相同路径导入函数,使用 JavaScript 写法;见下方选项式示例。平台构建能力及真机效果仍需在目标工程验证 |
| Android | 原生配置最低 Android 5.0 / API 21;不同品牌、系统版本和默认桌面的角标能力不同 |
| iOS | 原生配置最低 iOS 12;iOS 16+ 使用 setBadgeCount,旧系统使用兼容 API |
| 原生 HarmonyOS | 当前实现基于 API 12+,需使用支持相应鸿蒙平台的 HBuilderX / SDK |
| Web / 小程序 | 不支持系统桌面角标,不要在这些平台执行插件调用 |
| 网络、账号与推送 | 本地角标操作无需网络权限、AppKey、账号或推送服务;不负责接收远程消息 |
适配代码存在不等于所有机型都已通过验收。本文末尾单独列出真机结果及当前限制。
2. 集成步骤
2.1 导入完整插件目录
从插件市场导入,或把整个 yt-badge 文件夹复制到目标工程的 uni_modules 目录:
你的项目/
├── uni_modules/
│ └── yt-badge/
│ ├── package.json
│ ├── readme.md
│ └── utssdk/
│ ├── interface.uts
│ ├── unierror.uts
│ ├── index.uts
│ ├── app-android/
│ ├── app-ios/
│ └── app-harmony/
└── pages/
不要只复制某个 index.uts 或原生源码文件。Android 的 AndroidManifest.xml、res 和各平台的 config.json 都是集成内容。
2.2 在业务页面导入
import {
inspectBadgeEnvironment,
authorizeBadge,
updateBadge,
removeBadge,
openBadgeSettings,
BadgeReport,
BadgeError,
BadgeCompletion
} from '@/uni_modules/yt-badge'
无需 Vue.use()、组件注册或 uni.requireNativePlugin()。业务代码不需要直接导入 Kotlin / Swift 类。普通 uni-app JavaScript 页面只导入需要调用的函数,不导入 UTS 类型、不写 UTS 类型标注。
如果工程还发布 Web / 小程序,请用对应平台条件编译保护导入和调用,或提供自己的不支持提示。
2.3 编译到包含插件的原生包
2.4 核对当前运行包,再进行第一次调用
推荐接入顺序:
- 在真机打开 App,调用
inspectBadgeEnvironment()记录环境。 - 用户点击“开启提醒”后,在前台调用
authorizeBadge()。 - 检查
permissionState;iOS 同时检查badgeAllowed。Android 再按品牌检查系统桌面角标开关。 - 调用
updateBadge({ unread: 8, ... }),按 Home 返回桌面观察。 - 返回 App 调用
removeBadge({ ... }),再次回桌面确认清除。 - 在正式包上重复验证,并确认其它业务通知没有被误删。
Android 的 report.androidPackageName 是从当前运行 Context 读取的实际包名。标准调试基座、自定义基座和正式包可能是不同应用;通知开关与厂商资格也分别保存。
插件自动使用当前包和桌面入口。插件清单中的 uts.sdk.modules.ytBadge 是原生代码命名空间,不是业务包名,不要将它改成业务应用 ID。
3. uni-app x 完整调用示例
下面代码可作为已在 pages.json 注册的 .uvue 页面的内容。包含五个方法、按钮防重复点击、失败提示和返回设置后的状态刷新。示例固定写入 8,实际业务替换为服务端或本地消息系统计算出的未读总数。
<template>
<view class="badge-demo">
<text class="result">{{ resultText }}</text>
<text class="detail">{{ detailText }}</text>
<button :disabled="busy" @click="readEnvironment">检测环境</button>
<button :disabled="busy" @click="requestAccess">申请通知 / 角标权限</button>
<button :disabled="busy" @click="writeUnread">设置未读数为 8</button>
<button :disabled="busy" @click="clearUnread">清除角标</button>
<button :disabled="busy" @click="showSettings">打开系统设置</button>
<text class="detail">设置或清除后,请返回系统桌面检查 App 图标。</text>
</view>
</template>
<script setup lang="uts">
import { ref } from 'vue'
import { onShow } from '@dcloudio/uni-app'
import {
inspectBadgeEnvironment, authorizeBadge, updateBadge,
removeBadge, openBadgeSettings,
BadgeReport, BadgeError, BadgeCompletion
} from '@/uni_modules/yt-badge'
const busy = ref(false)
const resultText = ref('待检测')
const detailText = ref('先检测环境,再由用户主动申请权限。')
// success 表示本次接口流程完成。授权可能被拒绝,Android 也可能只提交了请求。
function showReport(report: BadgeReport): void {
resultText.value = report.operation + ' / ' + report.status
detailText.value = '平台:' + report.platform +
';通知权限:' + report.permissionState +
';通道:' + report.route + '\n' + report.note
console.log('[yt-badge]', report)
}
function showFailure(error: BadgeError): void {
resultText.value = '调用失败:' + error.errCode.toString()
detailText.value = error.errMsg
console.error('[yt-badge]', error.errCode, error.errMsg)
}
// 成功、失败都会进入 complete;统一在这里恢复按钮。
function finish(_result: BadgeCompletion): void {
busy.value = false
}
function readEnvironment(): void {
if (busy.value) return
// 必须在调用之前置为 true,参数校验失败可能立即触发回调。
busy.value = true
inspectBadgeEnvironment({ success: showReport, fail: showFailure, complete: finish })
}
function requestAccess(): void {
if (busy.value) return
busy.value = true
authorizeBadge({
// 只影响 iOS;即使两项都是 false,仍申请角标权限。
withSound: false,
withAlert: false,
success: showReport,
fail: showFailure,
complete: finish
})
}
function writeUnread(): void {
if (busy.value) return
busy.value = true
updateBadge({
unread: 8, // 绝对数量;不要传字符串 '8'。
android: {
delivery: 'auto', // 首次接入建议保留自动适配。
notificationTitle: '未读消息',
notificationText: '你有 8 条未读消息'
// 不填 activityName 和 smallIconName,使用自动入口及内置小图标。
},
success: showReport,
fail: showFailure,
complete: finish
})
}
function clearUnread(): void {
if (busy.value) return
busy.value = true
removeBadge({ success: showReport, fail: showFailure, complete: finish })
}
function showSettings(): void {
if (busy.value) return
busy.value = true
openBadgeSettings({ success: showReport, fail: showFailure, complete: finish })
}
// 从系统设置返回后重新检测;不会自动弹授权框,也不会重新写入角标。
onShow(() => {
readEnvironment()
})
</script>
<style>
.badge-demo { padding: 24px; }
.result { font-size: 18px; margin-bottom: 12px; }
.detail { font-size: 14px; margin-bottom: 16px; }
</style>
该页面将权限状态和系统说明直接展示出来。生产环境请把 errMsg 转换成适合业务的提示,并根据下文说明判断权限;不要把所有 success 都显示成“角标设置成功”。
普通 uni-app Vue3 选项式写法
以下是 .vue 页面的最小设置 / 清除示例。仍需先接入完整插件,并完成授权和系统设置;完整的环境检测、授权流程与上方相同。
<template>
<view>
<button :disabled="busy" @click="setUnread">设置为 8</button>
<button :disabled="busy" @click="clearUnread">清除角标</button>
<text>{{ message }}</text>
</view>
</template>
<script>
import { updateBadge, removeBadge } from '@/uni_modules/yt-badge'
export default {
data() {
return { busy: false, message: '请先完成通知 / 角标授权' }
},
methods: {
setUnread() {
if (this.busy) return
this.busy = true
updateBadge({
unread: 8,
success: (report) => { this.message = report.status + ':' + report.note },
fail: (error) => { this.message = error.errCode + ':' + error.errMsg },
complete: () => { this.busy = false }
})
},
clearUnread() {
if (this.busy) return
this.busy = true
removeBadge({
success: (report) => { this.message = report.status + ':' + report.note },
fail: (error) => { this.message = error.errCode + ':' + error.errMsg },
complete: () => { this.busy = false }
})
}
}
}
</script>
4. 方法与参数详解
所有方法都接收一个配置对象;没有额外参数时也要传 {},例如 removeBadge({})。建议始终提供 fail,避免静默忽略原生错误。
| 方法 | 参数类型 | 返回值 | 作用 |
|---|---|---|---|
inspectBadgeEnvironment(options) |
BadgeCallbacks |
void |
读取当前系统环境、权限及默认自动通道 |
authorizeBadge(options) |
BadgeAccessOptions |
void |
发起平台允许的授权流程,返回最新权限快照 |
updateBadge(options) |
BadgeUpdateOptions |
void |
设置绝对未读数量 |
removeBadge(options) |
BadgeCallbacks |
void |
清除角标,并撤销插件自己的 Android 通知 |
openBadgeSettings(options) |
BadgeCallbacks |
void |
打开当前应用的系统设置 / 通知设置 |
4.1 inspectBadgeEnvironment:读取环境
inspectBadgeEnvironment({
success: (report: BadgeReport) => {
console.log('平台', report.platform, '默认桌面', report.launcherPackage)
console.log('实际 Android 包名', report.androidPackageName ?? '')
console.log('通知权限', report.permissionState)
console.log('角标开关', report.badgeAllowed, '渠道角标', report.channelBadgeAllowed)
console.log('数字资格', report.androidNumberBadgeSupport ?? 'unknown')
},
fail: (error: BadgeError) => { console.error(error.errCode, error.errMsg) }
})
参数只有通用回调。此方法不弹授权框、不创建通知渠道、不修改角标。成功报告为 operation='inspect'、status='inspected'。
适合在首次进入页面、从设置返回、更换默认桌面后调用。首次安装尚未发布通知时,channelBadgeAllowed=null 是正常情况,不等于渠道被关闭。route 是当前环境检测到的自动通道,不是上一次写入通道的历史查询。
4.2 authorizeBadge:申请权限
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
withSound |
boolean |
否 | false |
iOS 额外申请声音权限 |
withAlert |
boolean |
否 | false |
iOS 额外申请通知提示权限 |
success / fail / complete |
函数 | 否 | 不传 | 通用回调,见第 5 节 |
authorizeBadge({
withSound: false,
withAlert: false,
success: (report: BadgeReport) => {
// 用户拒绝也可能正常进入 success,不能只判断回调名称。
if (report.permissionState != 'granted' || report.badgeAllowed == false) {
console.log('权限尚未满足,请提供“打开系统设置”按钮')
return
}
// Android 的独立桌面开关和厂商资格,还需按品牌检查。
console.log('系统授权状态已满足,下一步可调用 updateBadge')
},
fail: (error: BadgeError) => { console.error(error.errCode, error.errMsg) }
})
平台行为:
- Android:系统版本 Android 13 / API 33+,且应用
targetSdkVersion >= 33、通知权限尚未开启时,插件主动申请POST_NOTIFICATIONS。其它情况主要读取现有权限,不保证出现弹窗。旧目标版本的弹窗时机由系统控制;已拒绝、禁止再次询问等情况应引导用户到设置检查。 - iOS:始终请求角标权限;根据两项参数决定是否附加声音、提示权限。传
false不会撤销已有授权。授权总状态与独立“标记”开关要分别检查。 - 原生 HarmonyOS:请求启用应用通知,结束后重新查询状态;用户拒绝可能正常返回
permissionState='denied'。
请由前台页面中的用户操作触发。已有授权流程时再次调用返回 9310007,应等待第一次的 complete。不要在启动时反复强制申请,也不要期待重复调用能绕过用户拒绝。
Android 权限时机参考:Android 官方通知运行时权限说明。
4.3 updateBadge:写入绝对未读数
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
unread |
number |
是 | 无 | 0~2147483647 的有限整数;0 表示清除 |
android |
BadgeAndroidOptions |
否 | 自动配置 | Android 专属配置;iOS / HarmonyOS 忽略 |
success / fail / complete |
函数 | 否 | 不传 | 通用回调 |
不接受字符串、小数、负数、NaN、Infinity 或超出范围的值。接口允许的数值范围不等于桌面的显示范围;99+ 等缩略样式由系统决定。更新不会自动发起授权,权限不足时返回错误。
updateBadge({
unread: 12,
android: {
delivery: 'auto',
notificationTitle: '收件箱',
notificationText: '还有 12 封邮件未读'
},
success: (report: BadgeReport) => {
console.log('请求数量', report.requestedUnread)
console.log('本次通道', report.route, '结果状态', report.status)
},
fail: (error: BadgeError) => { console.error(error.errCode, error.errMsg) }
})
android 对象的全部字段
以下字段均为可选的 string:
| 字段 | 默认值 | 用法与注意事项 |
|---|---|---|
delivery |
'auto' |
只接受 auto、notification、launcher,具体行为见下表 |
activityName |
自动解析桌面入口 | 仅特殊多入口 / activity-alias 应用需要。填写当前应用中已注册的完整类名,或 .MainActivity 形式的相对类名;不是包名、页面路由或应用名称 |
notificationTitle |
未读消息 |
通知方式下的通知标题;纯厂商通道不发布这条通知 |
notificationText |
你有 N 条未读消息 |
通知正文,N 为本次 unread。自定义正文不会自动跟随你的业务数量变化,应同步生成 |
smallIconName |
yt_badge_small_icon |
通知小图标的 drawable 资源名称,不带扩展名和路径;资源必须已经打进当前安装包 |
delivery 如何选择
| 值 | 行为 | 建议用途 |
|---|---|---|
auto |
按当前默认桌面与适配情况选择通道。OPPO / 部分一加采用通知与厂商接口组合,其它适配情况见第 7 节 | 首次集成和常规业务推荐 |
notification |
强制使用真实系统通知,通过通知数量和渠道角标能力参与桌面显示 | 排查通知方式,或业务明确接受通知圆点 / 数字的场景 |
launcher |
仅请求已适配的厂商桌面接口;未适配时返回 9310002,不改走通知 |
已确认目标设备支持独立厂商通道的场景 |
launcher 不是“强制数字”开关,也不绕过通知权限、桌面开关或厂商资格。小米等默认走通知的桌面不应为了追求数字而强制此模式。
OPPO / 部分 ColorOS / 一加在 auto 下返回 route='oppo-notification':先发布通知,再请求厂商数字接口。厂商数字调用失败时可能保留通知并在 note 说明,供圆点显示;通知权限或渠道错误仍会进入 fail。如果系统已明确报告数字资格 unsupported,强制 launcher 写入正数会返回 9310005,并保留此前的插件通知。
部分 Provider 没有可靠回执。返回“未返回确认”不等于已显示,也不能一律认定失败;请结合 note 和实际桌面检查。
自定义通知小图标
先用内置图标完成接入;确有需要再添加自定义资源。例如在 uni-app x 工程中放置:
nativeResources/android/res/drawable/my_badge_notify.xml
XML 内容可使用适合通知栏的单色矢量图标。重新构建并安装包含该资源的原生包后,传入 smallIconName: 'my_badge_notify'。
这里设置的是通知栏小图标,不是桌面 App 图标。不要传图片 URL、static 文件路径、.png / .xml 后缀或 mipmap 名称。插件按 drawable 名称查找;找不到返回 9310001。正式包如果启用了资源裁剪或名称混淆,也要确认按名称查找的资源被保留。
4.4 removeBadge:清除角标
removeBadge({
success: (report: BadgeReport) => {
console.log(report.operation) // clear
console.log(report.requestedUnread) // 0
console.log(report.status, report.note)
},
fail: (error: BadgeError) => { console.error(error.errCode, error.errMsg) }
})
参数只有通用回调,不需要传数量。普通清除建议使用此方法;不额外指定 Android 选项时,updateBadge({ unread: 0 }) 同样用于清除,但报告 operation 为 update。
- Android:撤销插件自己发布的固定通知,并向适用桌面通道归零。优先使用上次成功提交时保存的通道与入口,未保存时按当前桌面自动适配。只保存通道和入口,不缓存一个“桌面真实数量”。
- iOS / HarmonyOS:调用系统角标 API 写入 0;不负责删除其它业务通知或通知中心历史。
- 清除不会因为插件自身的正数写入权限检查而被直接阻止,用户关闭权限后仍可尝试撤销已有角标;原生系统调用仍可能失败。
- Android 不会调用
cancelAll(),也不能删除系统通知助手或其它应用名下的通知。其它通知参与角标计数、系统桌面缓存未刷新时,图标可能仍有残留。 - 若厂商清除失败,插件通知可能已先撤销;
fail不表示此前所有子操作都已回滚。
切换默认桌面、删除入口、交替使用多种写入通道后,请重新验收清除效果。当前一加测试还存在桌面圆点残留,见第 11 节。
4.5 openBadgeSettings:打开设置
openBadgeSettings({
success: (report: BadgeReport) => {
console.log(report.status) // opened:只表示已打开设置
},
fail: (error: BadgeError) => { console.error(error.errCode, error.errMsg) }
})
参数只有通用回调。Android 优先打开本应用通知设置,旧系统或不支持时回退应用详情;iOS 打开本应用系统设置;HarmonyOS 打开通知设置。
此方法不会替用户开启开关,也不保证直接定位到厂商“桌面角标”的全局页面。用户可能还需手动进入品牌专属菜单。返回 App 后在 onShow 重新调用 inspectBadgeEnvironment(),不要把 opened 当成已授权。
5. 回调、报告与状态说明
5.1 通用回调 BadgeCallbacks
| 字段 | 回调参数 | 触发时机 |
|---|---|---|
success |
BadgeReport |
接口流程正常结束;需继续判断权限、状态和系统限制 |
fail |
BadgeError |
参数不合法、不支持、权限关闭或原生调用异常 |
complete |
BadgeCompletion |
在 success 或 fail 之后执行,用于结束 loading、恢复按钮 |
每次调用先触发 success 或 fail,再触发一次 complete。不要在回调中主动抛异常。参数校验等错误可能立即返回,因此要在调用前设置 loading / busy。
// 以下是回调参数的结构说明,不需要在业务中重新声明同名类型。
type BadgeCompletion = {
ok: boolean
report: BadgeReport | null // ok=true 时提供;失败为 null。
error: BadgeError | null // ok=false 时提供;成功为 null。
}
五个方法返回值均为 void,没有内置 Promise。 await updateBadge(...) 不能用于等待角标调用完成,应使用回调,或由业务自行封装 Promise。连续写入、清除应等待前一次 complete,避免业务操作互相覆盖。
5.2 BadgeReport 完整字段
| 字段 | 类型 | 含义 / 判断方式 |
|---|---|---|
operation |
string |
inspect / authorize / update / clear / settings |
platform |
string |
android / ios / harmony;按此字段区分原生平台 |
manufacturer |
string |
系统提供的厂商名;不要仅据此假定当前默认桌面支持数字 |
androidPackageName |
可选 string |
Android 当前实际运行包名;HarmonyOS 返回空字符串,iOS 不提供 |
androidNumberBadgeSupport |
可选 string |
部分 ColorOS / 一加可读的应用数字资格,见下方三态说明;其它环境可能为 unknown 或不提供 |
launcherPackage |
string |
Android 当前默认桌面的包名;其它平台为空字符串 |
permissionState |
string |
granted / denied / not-determined;不包含所有厂商独立角标开关 |
notificationsAllowed |
boolean |
当前应用级通知授权状态;不代表通知一定未被厂商过滤 |
badgeAllowed |
可空布尔值 | iOS 独立角标开关;Android / HarmonyOS 无统一查询,返回 null |
channelBadgeAllowed |
可空布尔值 | Android 插件渠道允许角标且渠道未被关闭;渠道尚未创建、Android 8 以下或其它平台为 null |
route |
string |
检测时为当前自动通道;写入 / 清除时为本次实际使用通道 |
requestedUnread |
number 或 null |
仅 update / clear 提供本次请求值,其他操作为 null;不是桌面数量读回 |
status |
string |
操作结果状态,见下表 |
note |
string |
当前操作说明、未确认事项与厂商限制,建议保留用于排查 |
布尔值为 null 表示不能统一查询或尚不适用,不是 false。不要写 if (!report.badgeAllowed) 来判断所有平台的角标关闭;检查明确关闭时使用 report.badgeAllowed == false。
数字资格的三个值:
| 值 | 含义 | 业务处理 |
|---|---|---|
supported |
系统报告本应用具备数字能力 | 仍需启用桌面模式及应用开关,不代表已显示 |
unsupported |
系统报告当前应用未获数字能力 | 不反复尝试强制数字;可在系统允许时使用通知圆点 |
unknown / 字段缺省 |
查询不可用、受限或当前平台未提供该能力 | 不能当作“不支持”;以目标机型系统设置与实测为准 |
此字段只查询当前应用,不申请数字资格、不修改厂商名单、不更改其它应用设置。
5.3 status 的准确含义
| 状态 | 含义 | 能否据此断言桌面已显示? |
|---|---|---|
inspected |
环境读取完成 | 不能,没有写入 |
authorized |
授权流程结束 | 不能,用户可能拒绝 |
submitted |
Android 请求已提交 / 广播已发送 | 不能,系统可能过滤、忽略或尚未刷新 |
applied |
iOS / HarmonyOS 系统角标 API 完成 | API 已完成,实际样式、上限和显示仍由系统控制 |
opened |
已打开设置 | 不能,需返回后重新检测 |
常见 route:notification(系统通知)、huawei-provider、honor-provider、vivo-broadcast、oppo-provider(仅厂商接口)、oppo-notification(通知与厂商接口组合)、samsung-broadcast(旧三星)、ios、harmony。
插件没有读取“桌面真实未读数字”的方法。requestedUnread、complete.ok=true 和上次业务缓存都不能作为桌面绘制成功的回执。
6. Android 通用设置与通知机制
6.1 先检查这些条件
- 当前安装包的应用通知已开启;Android 13+ 还要检查运行时通知授权。
- 默认桌面支持通知角标,并已启用全局角标及本应用开关。
- 若系统提供“数字 / 圆点 / 混合”选项,选择当前应用可用的模式。
- 通知方式下,插件渠道允许通知和角标,且通知没有被通知助手、折叠或过滤规则拦截。
- 返回系统桌面观察实际图标,确认观察的是当前包,而不是旧版本、标准基座、应用分身或另一用户空间中的图标。
厂商菜单会随系统版本、地区和桌面版本变化。下文提供常见入口与搜索关键词,以手机实际菜单为准。不要为了排查角标直接清空系统桌面数据,这会影响桌面布局。
6.2 插件已经声明的原生内容
Android 插件目录已包含通知权限、已适配厂商所需的角标权限、桌面 / Provider 查询声明和内置小图标。正常完整导入后不需要再复制一份权限清单;若项目配置了权限裁剪或离线打包,应确认所需内容没有被剔除。
添加厂商权限声明不等于获得数字资格。尤其在部分 ColorOS 上,通知授权、渠道角标、用户显示模式、应用数字资格是不同条件。
6.3 通知方式会显示什么
| 项目 | 当前插件行为 |
|---|---|
| 通知渠道 ID / 名称 | yt_badge_unread_v1 / 未读消息角标 |
| 固定通知 tag / id | yt-badge.unread / 18901 |
| 连续更新 | 复用同一条通知,不因多次设置 8、3、1 而堆积三条插件通知 |
| 数量 | 设置通知的 number;桌面是否显示该数字由 Launcher 决定 |
| 初始声音 / 振动 | 创建渠道时默认关闭;已有渠道遵从用户和系统保存的设置 |
| 点击通知 | 尝试打开当前 App;业务应自行决定何时清除未读,插件不自动将业务数量归零 |
| 用户划掉通知 | 部分桌面的对应圆点 / 数字会随之消失 |
| 清除 | 只撤销上述固定通知,不删除其它业务通知 |
Android 8+ 渠道在第一次发布通知时创建。渠道被关闭或不允许角标时返回 9310004;插件不会换一个渠道 ID 绕过用户选择。渠道已创建后,重新调用或重新运行页面不会自动覆盖用户修改的设置。
纯华为 / 荣耀 Provider、vivo 广播等方式不依赖插件额外发布这条通知;但本插件的正数写入仍检查应用通知权限。notificationTitle 等字段在这些方式下不会生成通知。
Android 官方说明:通知角标与自定义数量、NotificationChannel.canShowBadge。这些能力不能保证所有桌面都显示数字。
7. Android 各品牌设置及限制
7.1 小米 / Redmi / POCO:检查通知过滤
插件默认方式:系统通知,MIUI 扩展可用时同时写入通知消息数。建议 delivery='auto'。
常见操作:
- 打开“设置 → 通知与状态栏”,旧版可能叫“通知与控制中心”。
- 进入“桌面角标 / 角标”,开启本应用。
- 在本应用通知设置中打开“允许通知 / 显示通知”,检查
未读消息角标渠道。 - 若提供角标样式,选择需要且系统允许的显示方式;写入后按 Home 返回桌面。
菜单参考:小米官方角标设置说明。不同 MIUI / HyperOS 的入口和样式选项可能不同。
MIUI 12.5 真机遇到的额外条件: 应用通知、桌面角标、渠道均已开启,但“通知过滤规则”为“系统推荐”时,通知仍被系统助手拦截。MI CC 9 上将本应用通知设置中的规则改为 “全部设为重要(不折叠该应用的全部通知)”,重新写入后数字角标正常。
该规则属于厂商过滤策略,notificationsAllowed=true 无法证明它已放行。若没有这项菜单,请检查本机的通知折叠 / 不重要通知等入口,不要求所有 HyperOS 都使用同一选项。
修改规则后,系统可能恢复此前被折叠的旧通知。若“设置 8 却显示 9”或“清除后剩 1”,先检查通知栏是否有恢复的旧消息;手动划掉属于本应用的那条旧消息,再重新测试。恢复消息有时归系统助手所有,插件不能删除它。
已验证机型与过程见 MI CC 9 真机记录。
7.2 华为 Android / EMUI:检查桌面角标开关
Android APK 的默认桌面被识别为华为 Launcher 时,使用 huawei-provider。 无需为角标额外生成插件通知。
在设置中搜索“桌面图标角标 / 桌面角标”,检查全局显示方式及当前应用开关;同时允许本应用通知。如果系统提供数字与通知圆点的选择,按实际需要设置,再重新写入验证。
参考:华为桌面角标设置说明。手机显示的系统名称不能单独决定插件走哪套实现:报告 platform='android' 时看本节;platform='harmony' 的原生鸿蒙应用看第 8 节。
换用第三方桌面后,不应继续假定华为 Provider 一定生效;请查看新的 launcherPackage 和 route。
7.3 荣耀 / Magic UI / MagicOS:先确认本应用是否提供数字选项
识别到荣耀 Launcher 时,使用 honor-provider;部分系统在对应 Provider 不存在时兼容华为通道。
在“设置 → 通知和状态栏 / 通知中心 → 桌面图标角标”等入口开启本应用,确认通知权限。若提供角标显示方式,选择数字;若本应用只提供通知圆点或不在数字选项列表中,不能靠 launcher 参数强行开放数字。
荣耀官方也区分应用数字角标与通知消息角标;具体资格和显示规则取决于机型 / 系统:应用角标不显示数字的说明。
已有 Honor 8X 设置、清除成功的用户反馈;这不代表所有 MagicOS 版本都已经验收。当前数字资格查询字段主要用于部分 ColorOS / 一加,不要期待它在荣耀上总能返回明确结果。
7.4 OPPO / 一加 / 部分 realme:通知开关与数字资格分开检查
识别到相应 OPPO / ColorOS / 一加桌面,或提供兼容 BadgeProvider 的桌面时,auto 使用 oppo-notification。 realme 需以实际检测到的默认桌面及通道为准,不能只看品牌。
常见入口为“设置 → 通知与状态栏 → 桌面角标”,也可搜索“角标”。检查全局数字 / 圆点 / 混合模式,以及本应用的通知与角标选项。若应用没有数字资格,使用本机允许的“混合 / 圆点”模式观察通知圆点。
排查时分别记录:
- 应用通知是否允许:
notificationsAllowed。 - 插件渠道是否允许角标:
channelBadgeAllowed。 - 本应用数字资格:
androidNumberBadgeSupport。 - 系统全局模式及当前应用角标选项:到手机设置中手动核对。
前三者不是同一个开关。supported 仍不保证显示;unknown 也不能认定没有资格。unsupported 表示当前查询结果明确否定数字能力,强制 launcher 不能改变结果。
为什么微信有数字,而新应用没有? 本项目的一加 9R / ColorOS 14 实测中,微信的应用级数字资格为 true,示例包为 false;系统桌面预置名单包含微信、不包含示例包。该手机具有数字显示能力,但没有向当前示例包开放。同机其它应用能显示数字,不能证明新应用一定有资格。应按对应系统的厂商接入要求处理,不要冒用其它应用包名。
这台一加已看到自动模式圆点和通知数量连续更新,但最新复测仍有通知已撤销、桌面旧圆点残留的问题,清除尚未通过验收。单独通知模式也出现过残留,原因未确定,不能将其简单归因于数字 Provider,也不能把重启桌面当成插件正常清除能力。
详见 一加数字资格与清除诊断。此结论限定于记录中的机型、系统与测试包,不推广为所有一加 / OPPO 的固定策略。
7.5 vivo / iQOO:检查当前桌面的数字角标能力
识别到受适配的 vivo 默认桌面时,使用 vivo-broadcast。 广播发送没有可靠的桌面绘制回执。
在系统设置中搜索“桌面角标 / 显示桌面角标”,打开本应用开关;部分版本入口位于“通知与状态栏”。若当前 OriginOS / Funtouch OS 提供数字选项,选择后再测试。菜单可参考 vivo 社区中的设置示例,实际以设备为准。
同时开启应用通知。更换第三方桌面、当前系统不接受该广播或未提供数字选项时,不能以 submitted 判定已显示。本项目目前没有 vivo / iQOO 真机验收记录。
7.6 三星 / One UI:数字来源于通知徽章
Android 8+ 默认走系统通知;旧版受适配三星桌面使用 samsung-broadcast。
常见入口:“设置 → 通知 → 高级设置 → 应用程序图标标记 / 应用图标徽章”。开启后选择“数字”或“圆点”,再确认本应用及插件渠道通知开启。
参考:三星官方应用图标徽章设置说明。通知聚合、用户清理通知及桌面样式会影响数字;unread=8 不保证每个 One UI 版本都按同样方式显示 8。目前没有三星真机验收记录。
7.7 魅族 / 原生 Android / 其它品牌 / 第三方桌面
没有匹配到已适配厂商通道时,默认使用 notification。本插件没有为所有魅族历史桌面实现专有协议;AOSP 风格或第三方 Launcher 可能只支持圆点,也可能要求单独启用通知角标。
在桌面设置中搜索“通知圆点 / 图标徽章 / 角标”,开启对应能力,并检查应用通知与渠道。如果桌面只支持圆点,没有跨厂商参数能把它变为数字。强制 launcher 在未适配时返回 9310002。
应用分身、工作资料、多用户空间可能有独立的通知与桌面规则。插件仅操作当前运行应用,不会替另一个用户空间或另一份安装包设置角标。
8. iOS 与原生 HarmonyOS 设置
8.1 iOS
- 在前台用户操作后调用
authorizeBadge();只需角标时,两项附加授权参数可保持false。 - 到“设置 → 通知 → 本应用”检查“允许通知”及“标记 / 角标”;部分 iOS 版本也可从“设置 → App → 本应用”进入通知设置。
permissionState='granted'后,还应确认badgeAllowed=true。总通知授权允许不代表独立标记开关一定开启。- 写入后返回桌面检查;清除使用
removeBadge()。
iOS 使用系统角标 API,不额外发布一条本地通知承载角标。仅本地设置 / 清除角标不要求接入 APNs、推送证书或远程推送服务。若用户关闭标记,正数写入返回 9310004;反复授权不能强行开启用户开关。
清除图标角标不会删除通知中心其它消息。远程推送 payload 中的 badge、其它 SDK 或业务代码再次写入时,可能覆盖本插件结果,需统一数量来源。
接口参考:Apple setBadgeCount。
8.2 原生 HarmonyOS
报告为 platform='harmony'、route='harmony' 时,使用 NotificationKit 的系统角标 API;android 参数全部忽略。
在前台调用 authorizeBadge() 请求启用通知;也可调用 openBadgeSettings() 打开本应用通知设置。检查“允许通知”,以及系统提供的“桌面角标 / 提醒方式”选项。常见入口为“设置 → 通知和状态栏 → 本应用”,具体名称以系统版本为准。
badgeAllowed、channelBadgeAllowed 为 null 是正常情况,插件不伪造独立开关查询结果。写入正数要求通知已允许;显示上限由系统决定。该实现不需要 Android 厂商角标权限,也不涉及录音,无需为它添加麦克风权限。
已有华为 nova 14 / HarmonyOS 7.0.0 设置、清除成功的用户反馈。参考:华为桌面角标设置、HarmonyOS notificationManager。
9. 业务接入与后台调用
9.1 数量由业务维护
插件不维护消息数据库,也没有“加一 / 减一 / 读取当前桌面数字”的业务接口。建议以服务端未读总数或统一的本地消息状态为准,每次调用写入最新绝对值。
- 收到新消息、消息列表同步完成:
updateBadge({ unread: 最新总数, ... })。 - 阅读部分消息后:重新计算未读总数,再覆盖写入。
- 全部已读、退出账号或切换到无未读账号:根据业务需要调用
removeBadge()。 - 从后台回来:需要时同步业务未读数,不要无条件写入固定演示值。
- 推送 SDK、其它通知模块也会设置角标时:统一入口和数量来源,避免互相覆盖或重复计数。
不要在每次 onShow 无条件清除,除非业务规定“打开应用即视为全部已读”。同样,点击通知不会自动说明用户已经阅读全部消息。
9.2 后台调用的边界
五个方法不要求页面组件实例;但授权和打开设置应在前台用户操作中执行。后台设置 / 清除仍受系统生命周期与执行限制,插件不是保活服务,也不保证进程被终止后继续运行。
本演示工程的“切到后台写入”由 pages/index.uvue 保存一次临时任务,App.uvue 的 onAppHide 调用 pages/badge-demo-task.uts 中的 applyQueuedBadgeDemo() 消费任务,再执行 updateBadge()。即时写入、清除或取消会取消尚未执行的任务,避免旧数量稍后覆盖新数量。
普通接入只需复制插件目录,不必复制演示工程的 App.uvue。需要后台演示时,再阅读并整合上述两个业务文件与应用生命周期;不要只复制一个按钮或直接覆盖自己的 App.uvue。
10. 错误码与问题排查
10.1 BadgeError
type BadgeError = {
errCode: number
errSubject: string // 固定为 'yt-badge'。
errMsg: string // 具体原因,排查时保留完整文本。
}
| errCode | 含义 | 建议处理 |
|---|---|---|
9310001 |
参数错误,或指定入口 / 图标资源不合法 | 检查整数范围、delivery 拼写、Activity / alias 是否已注册、drawable 是否打进包中 |
9310002 |
当前平台或独立桌面通道不支持 | Web / 小程序不调用;Android 优先恢复 auto,检查默认桌面 |
9310003 |
原生上下文 / 应用入口不可用 | 在 App 前台页面申请权限,核对当前包是否具备有效桌面入口;多入口才显式配置 activityName |
9310004 |
通知、独立角标或通知渠道权限关闭 | 按 errMsg 授权或引导进入对应设置,返回后重新检测 |
9310005 |
厂商接口拒绝或明确没有数字资格 | 检查 ROM、应用资格和厂商通道;明确无数字资格时使用可用的圆点模式 |
9310006 |
原生调用或结果处理异常 | 保留平台、系统版本、errMsg、操作步骤和日志,确认原生包与当前插件版本一致 |
9310007 |
已有授权流程进行中 | 等待前一次 complete,增加按钮防重复点击 |
10.2 常见现象
| 现象 | 优先检查 |
|---|---|
success 了但桌面没变化 |
看 status、route、note;Android 的 submitted 无绘制回执。核对实际包、默认桌面、通知 / 渠道 / 品牌开关 |
| 通知方式没有通知栏消息 | 检查应用通知、渠道、厂商通知过滤;小米重点检查通知助手 / 折叠规则 |
| 通知存在但没有数字 | 检查桌面模式、应用角标开关和数字资格;有些桌面只支持圆点 |
| 微信等有数字,本应用没有 | 不同应用可能有不同厂商资格;部分 ColorOS / 一加可查看 androidNumberBadgeSupport,不能只凭同机其它 App 推断 |
badgeAllowed=null |
Android / HarmonyOS 无统一查询,属于未知,不等于关闭 |
channelBadgeAllowed=null |
可能尚未发布第一条通知、Android 版本低于 8,或不是 Android;不要直接当作拒绝 |
| 传入 8 显示 9,清除剩 1 | 可能有其它业务通知或系统助手恢复的旧通知参与计数;检查通知栏,不要清空无关通知 |
| 清除返回成功,但旧圆点还在 | 确认插件通知是否撤销、是否仍有其它通知 / 推送重写、桌面是否刷新;当前一加还存在未解决的残留记录 |
smallIconName 找不到 |
只传 drawable 名称;确认完整资源已重新构建进当前安装包,且未被资源优化移除 / 改名 |
await 后就执行了下一步 |
方法返回 void;把后续动作放入回调,连续操作等待 complete |
| 从设置回来状态还是旧的 | 在 onShow 再检测;opened 不表示授权已经改变 |
| 自定义基座正常、正式包异常 | 核对两个包的实际包名、桌面入口、权限 / 资源合并、系统开关及厂商数字资格 |
若输入框返回字符串,在业务侧先校验并转换为数值再传入。uni-app x Android 不要直接使用 Number(text);可先验证纯数字格式,再用 parseInt(text, 10),随后检查有限整数及上限。
需要反馈问题时,请提供:机型、系统 / ROM 版本、默认桌面、实际包名、所调用方法与参数、完整报告或错误、通知栏与桌面观察结果。不要只提供“调用成功”截图。
11. 真机记录与验收建议
以下区分本项目真机记录与用户反馈,不代表同品牌所有机型都兼容:
| 设备 / 系统 | 记录来源 | 已确认结果与限制 |
|---|---|---|
| MI CC 9 / Android 11 / MIUI 12.5.5 | 本项目真机验证 | 数字 1、8、128、连续更新、removeBadge 与写 0 清除通过;需要放行通知过滤,恢复的旧消息需单独处理 |
| 另一台小米,型号 / 系统未提供 | 用户反馈 | 开启桌面角标后设置、清除正常;不补充推断显示样式 |
| Honor 8X,系统版本未提供 | 用户反馈 | 设置、清除正常;其它 MagicOS 版本及样式未据此确认 |
| OnePlus 9R / Android 14 / ColorOS 14 | 本项目真机验证 | 当前示例包数字资格为 false;自动模式通知数量与圆点更新已确认,最新复测清除后桌面仍有旧圆点,清除未通过 |
| 华为 nova 14 / HarmonyOS 7.0.0 | 用户反馈 | 设置、清除正常,属于原生 HarmonyOS 记录 |
| iPhone 12 / iOS 26.6 | 用户反馈 | 复测成功,原生结果解析修复后已确认 |
| vivo / iQOO / OPPO 其它机型 / realme / 三星 / 魅族等 | 尚无本项目真机验收 | 需按目标机型验证,不以已有适配代码代替测试 |

收藏人数:
购买源码授权版(
试用
使用 HBuilder 导入示例项目
赞赏(0)
下载 703
赞赏 16
下载 12773692
赞赏 1960
赞赏
京公网安备:11010802035340号