更新记录

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. 支持范围与接入条件

项目 说明
插件类型 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 核对当前运行包,再进行第一次调用

推荐接入顺序:

  1. 在真机打开 App,调用 inspectBadgeEnvironment() 记录环境。
  2. 用户点击“开启提醒”后,在前台调用 authorizeBadge()。
  3. 检查 permissionState;iOS 同时检查 badgeAllowed。Android 再按品牌检查系统桌面角标开关。
  4. 调用 updateBadge({ unread: 8, ... }),按 Home 返回桌面观察。
  5. 返回 App 调用 removeBadge({ ... }),再次回桌面确认清除。
  6. 在正式包上重复验证,并确认其它业务通知没有被误删。

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。正式包如果启用了资源裁剪或名称混淆,也要确认按名称查找的资源被保留。

参考:DCloud Android 原生资源配置。

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 先检查这些条件

  1. 当前安装包的应用通知已开启;Android 13+ 还要检查运行时通知授权。
  2. 默认桌面支持通知角标,并已启用全局角标及本应用开关。
  3. 若系统提供“数字 / 圆点 / 混合”选项,选择当前应用可用的模式。
  4. 通知方式下,插件渠道允许通知和角标,且通知没有被通知助手、折叠或过滤规则拦截。
  5. 返回系统桌面观察实际图标,确认观察的是当前包,而不是旧版本、标准基座、应用分身或另一用户空间中的图标。

厂商菜单会随系统版本、地区和桌面版本变化。下文提供常见入口与搜索关键词,以手机实际菜单为准。不要为了排查角标直接清空系统桌面数据,这会影响桌面布局。

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'。

常见操作:

  1. 打开“设置 → 通知与状态栏”,旧版可能叫“通知与控制中心”。
  2. 进入“桌面角标 / 角标”,开启本应用。
  3. 在本应用通知设置中打开“允许通知 / 显示通知”,检查 未读消息角标 渠道。
  4. 若提供角标样式,选择需要且系统允许的显示方式;写入后按 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

  1. 在前台用户操作后调用 authorizeBadge();只需角标时,两项附加授权参数可保持 false。
  2. 到“设置 → 通知 → 本应用”检查“允许通知”及“标记 / 角标”;部分 iOS 版本也可从“设置 → App → 本应用”进入通知设置。
  3. permissionState='granted' 后,还应确认 badgeAllowed=true。总通知授权允许不代表独立标记开关一定开启。
  4. 写入后返回桌面检查;清除使用 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 / 三星 / 魅族等 尚无本项目真机验收 需按目标机型验证,不以已有适配代码代替测试

隐私、权限声明

1. 本插件需要申请的系统权限列表:

Android:POST_NOTIFICATIONS 与厂商桌面角标权限;iOS:通知/角标授权;HarmonyOS:通知授权

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据”

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。