更新记录

1.1.0（2026-10-23）

兼容蒸汽模式

平台兼容性

uni-app(5.26)

uni-app x(5.26)

其他

UTS 应用角标与未读数（通知联动、权限管理）

为 Android / iOS App 提供角标设置、清空和本地通知联动，适合消息、订单、待办等未读数提醒。可查询设备建议策略，附可直接沿用的演示页。

HBuilderX 5.26+；版本 1.1.0；插件 ID：austin-badge-x。

Web、小程序、鸿蒙、Vue2 和 nvue 不在本版支持范围。Android 显示数字还是圆点，由系统桌面决定；通知提交成功不代表桌面一定出现角标。

第 1 步：导入插件

插件放在 你的项目/uni_modules/austin-badge-x/，uni_modules 与项目的 manifest.json、pages.json 同级，保留目录内全部文件。

在业务页面的 <script setup lang="uts"> 中这样导入：

import { getBadgeSupportInfo, setBadgeCount, clearBadge } from '@/uni_modules/austin-badge-x'

@/ 表示项目源码目录，上述路径对应 你的项目/uni_modules/austin-badge-x/。HBuilderX 会按 Android / iOS 自动选择原生实现。完整按钮示例见第 3 步。

第 2 步：通知权限与自定义基座

Android 插件自动合并以下权限；Android 13+ 还需调用权限申请 API。

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="com.huawei.android.launcher.permission.CHANGE_BADGE" />
<uses-permission android:name="com.hihonor.android.launcher.permission.CHANGE_BADGE" />
<uses-permission android:name="com.vivo.notification.permission.BADGE_ICON" />

iOS 首次使用前申请通知授权，并在系统设置中允许该 App 的“角标”。本插件只使用本地通知，不需要 P8、APNs、App Groups 或后台模式，也不需要新增隐私用途说明。

1. HBuilderX 选中项目，进入 发行 → 原生 App 云打包，勾选 制作自定义调试基座。
2. Android 填写应用包名和打包要求的签名信息；iOS 填写与 Bundle ID 匹配的 P12、证书密码及 .mobileprovision 描述文件，真机调试使用包含该 iPhone UDID 的 Development 或 Ad Hoc 描述文件，证书类型需与其匹配。
3. 打包完成后安装新基座，在运行菜单选择 自定义基座 再运行项目。进入演示页后点“申请通知权限”，按系统提示允许。

首次导入、更新原生代码或修改权限后重新制作基座；只改页面和调用参数时正常运行即可。完整基座操作见 DCloud 自定义基座说明。

尚无 iOS 签名材料时：按 Apple CSR 流程 申请开发证书，在生成 CSR 的 Mac 钥匙串中将证书连同私钥导出为 P12；注册 Bundle ID、添加测试设备 UDID，再按 Apple 开发描述文件流程 选择该 App ID、证书和设备，下载 .mobileprovision。

第 3 步：最小调用

下面的按钮先申请权限，再发送一条携带未读数的本地通知。返回手机桌面查看角标，通知中心查看通知。

<template>
  <view class="page">
    <button @click="showUnread">提醒 9 条未读消息</button>
    <text>{{ message }}</text>
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import {
  requestBadgePermissionIfNeeded,
  syncBadgeWithNotification,
  BadgePermissionResult,
  BadgePermissionOptions,
  BadgeNotificationOptions
} from '@/uni_modules/austin-badge-x'

const message = ref('')
function showUnread(): void {
  const permissionOptions: BadgePermissionOptions = {
    success: (_permission: BadgePermissionResult) => {
      const notificationOptions: BadgeNotificationOptions = {
        count: 9,
        title: '未读消息',
        content: '你有 9 条消息待查看'
      }
      const result = syncBadgeWithNotification(notificationOptions)
      message.value = result.ok ? result.note : result.errMsg
    },
    fail: (result: BadgePermissionResult) => {
      message.value = result.errMsg
    }
  }
  requestBadgePermissionIfNeeded(permissionOptions)
}
</script>

<style>
.page { padding: 24px; }
</style>

count 是应用总未读数的绝对值，不会自动累加或维护业务消息数。普通 Vue3 将 lang="uts" 改为 lang="ts"。只更新角标时调用 setBadgeCount({ count: 9 })；清空使用 clearBadge()。Android 纯设置主要适用于华为 / 荣耀、vivo，其他桌面优先使用通知联动。

第 4 步：运行演示或复制页面

在 pages.json 的 pages 数组追加：

{ "path": "uni_modules/austin-badge-x/index", "style": { "navigationBarTitleText": "应用角标与未读数", "disableScroll": true } }

打开演示：

uni.navigateTo({ url: '/uni_modules/austin-badge-x/index' })

1. 点 申请通知权限，按系统提示允许。
2. 用 1 / 9 / 99 / 清空 测试直接设置，再返回桌面查看。
3. 选择通知预设或编辑标题、正文，点通知联动，再查看通知中心与桌面。
4. 未显示时，展开设备诊断查看建议策略；到通知设置开启通知、角标及渠道开关。

沿用页面：将 uni_modules/austin-badge-x/index.uvue 复制为 pages/badge/index.uvue，在 pages.json 注册 pages/badge/index。普通 Vue3 复制 uni_modules/austin-badge-x/index.vue，目标为 pages/badge/index.vue。页面内的 @/uni_modules/austin-badge-x 导入保持原样，按业务修改按钮、预设和样式。

API

输入参数

BadgeCountOptions：

BadgeNotificationOptions 包含 count、title、content、notificationId，规则同上，另有：

以上两个计数 API 的 options 省略或传 null 时按 count=0 处理，建议显式传入计数。Android 的 setBadgeCount({ count: 0 }) 会调用 clearBadge()，结果 action 也为 clearBadge；iOS 只清角标，需要移除本插件全部通知时使用 clearBadge()。

BadgePermissionOptions 的 success、fail、complete 均为可选回调，参数为 BadgePermissionResult。已授权时直接回调，不重复弹窗；用户拒绝后可调用设置 API。每次请求先调用 success 或 fail，再调用 complete。

操作结果：BadgeResult

权限结果：BadgePermissionResult

设备诊断：BadgeSupportInfo

枚举与诊断字段

Android debug 按调用返回以下可选字段：launcherActivityClassName（应用入口）、homeLauncher.packageName/className（系统桌面）、defaultChannelId / channelId、defaultChannelSnapshot / channelSnapshot（渠道）、activeNotifications（通知快照）、vendorStrategy、recommendedStrategy、notified、isHuaweiFamily/isVivoFamily/isXiaomiFamily/isOppoFamily。

渠道快照包含 channelId、notificationsEnabled、notificationPermissionGranted、channelSupported，Android 8+ 另有 channelExists；存在时返回 channelName、channelImportance、channelCanShowBadge、channelDescription。通知快照包含 supported，支持时返回 count、ids、channels，读取失败时为 error。

错误处理

平台限制

• Android：数字、圆点及计数方式由桌面决定。华为 / 荣耀、vivo 可尝试厂商方案；小米 / Redmi 和通用 Android 优先使用通知联动；OPPO / ColorOS 数字角标通常涉及厂商能力申请，本插件不会代申请或绕过限制。
• 通知渠道：用户可单独关闭通知、渠道或角标；修改渠道名称或重复调用不会覆盖用户选择。openNotificationSettings().ok=true 只表示提交跳转，回到 App 后重新查询。
• 清理范围：clearBadge() 清空应用角标，移除本插件记录的通知，保留宿主其他通知；syncBadgeWithNotification({ count: 0, notificationId: 9001 }) 只移除对应 ID 的插件通知并清空角标。
• iOS：角标由系统管理；本插件不替换宿主的通知 delegate，前台是否显示横幅沿用宿主配置。通知是本地即时提醒，不是远程推送。