tmui4x 2.0(Vapor)

主题

TMUI4x2026-09-21
1676
6.6m

x-appicon-s 应用图标与角标 ​

类似淘宝：运行时切换预置桌面图标，并设置桌面角标数字 / 小红点。标准 -s API 插件，页面 import 后直接调用。

远程图片不能作为桌面图标。 iOS、Android、HarmonyOS 都要求图标打进安装包（或走应用市场上架的图标管理）。本插件内置 default / sanbu / zuoyiqi / shuijiao / wangwang / black 六套图；要换自己的图，替换插件资源并保持同名即可。

切换图标、角标都要自定义基座 / 云打包后才生效。部分桌面不会立刻刷新，回到桌面等几秒，或重新打开桌面。

兼容性 ​

能力AndroidiOSHarmonyOSWEB微信小程序
切换桌面图标支持（activity-alias）支持（Alternate Icon）当前 SDK 不支持本地切换标签页 favicon + Safari 主屏幕 / 程序坞大图标不支持
远程图片当图标不支持不支持不支持不支持不支持
数字角标支持（通知点 + 厂商通道）支持支持标签标题闪烁，如 (5) 标题不支持
纯红点支持（通知点）不支持，会显示 1不支持，会显示 1标签标题 ● 闪烁不支持

平台差异说明 ​

同一套 API，各端能做到的事不一样。系统没有「任意换桌面图 / 只改角标数字」的统一能力，插件只能对齐各端官方接口。

动态图标 ​

端实际改的是什么注意
Android多个 图标内置
iOSAlternate Icon静默切换，图标内置
HarmonyOS当前工程 SDK 没有本地切图标接口xSetAppIcon 返回 1008。上架图标管理要走 AGC，且 alternateIcons 从 API 26 才有
Web当前页 favicon + Safari apple-touch-icon不能改操作系统桌面图标。Safari「添加到主屏幕 / 程序坞」用大图；已经钉在桌面上的图标不会自动变，要去掉后重新添加
微信小程序不支持1008

角标数字 / 红点 ​

没有全机型通用的「只改桌面数字、不发通知」API。xSetAppBadge 成功只表示本端接口调用成功，不保证桌面立刻画出数字。

端数字纯红点实际机制
Android 8+ 原生桌面一般没有，数字在长按菜单里有未读通知就显示圆点Notification badges，通道需 setShowBadge(true)
小米 / 红米 / HyperOS有，跟通知计数走系统设置里可选「仅点 / 数字」，应用侧不能单独指定必须留一条可见通知，并打开应用「桌面角标」。静默 / LOW 通道常常不计数
华为 / 荣耀 / OPPO / vivo / 三星厂商接口支持数字看桌面实现走各厂商 ContentProvider / 广播，同时仍发通知作 Android 8+ 兜底
iOS支持没有纯红点，会显示 1需要通知授权（含 badge）
HarmonyOS支持没有纯红点，会显示 1notificationManager.setBadgeNumber
Web写在标签标题上闪烁，如 (5) 标题标题前加 ● 闪烁改 document.title，不是桌面角标
微信小程序不支持不支持1008

红米还要单独打开「桌面角标」，和通知权限不是一回事：

  1. 设置 → 通知管理 → 本应用 → 打开通知
  2. 同一页打开「桌面角标」
  3. 总开关：设置 → 通知与状态栏 → 桌面角标

设置成功后，通知栏会留一条「消息提醒」。这是小米用通知计数画角标，不是失败。

调用 ​

ts
import {
  xSetAppIcon,
  xSetAppBadge,
  xGetAppIconCapabilities,
  XSetAppIconOptions,
  XSetAppBadgeOptions
} from "@/uni_modules/x-appicon-s"

const caps = xGetAppIconCapabilities()

xSetAppIcon({
  name: "sanbu",
  success: (res) => {
    console.log(res.name)
  }
} as XSetAppIconOptions)

xSetAppBadge({
  count: 5,
  success: (res) => {
    console.log(res.count)
  }
} as XSetAppBadgeOptions)

预置图标 ​

name说明
default默认白底
sanbu散步
zuoyiqi坐一起
shuijiao睡觉
wangwang汪汪
black黑底

Android 图标在 utssdk/app-android/res/mipmap-*。iOS 图标在 utssdk/app-ios/Resources/x_appicon_{name}@2x.png 与 @3x.png。

方法 ​

名称说明
xSetAppIcon切换预置桌面图标。url 非空会 fail 1006。Web 改标签页图标和 apple-touch-icon
xResetAppIcon恢复默认图标
xGetAppIcon查询当前图标名
xGetSupportedAppIcons可切换图标列表
xSetAppBadge设置角标。count: 0 清除；showDot: true 尽量只显示红点。Web 写在标签标题上闪烁
xGetAppBadge查询当前角标
xClearAppBadge清除角标
xGetAppIconCapabilities同步返回平台能力

错误码 ​

码含义
1001系统错误
1002参数错误
1004通知 / 角标权限被拒绝
1006不支持远程图片作为桌面图标
1008当前平台不支持此功能
1009未找到 Android 图标别名，需要自定义基座

Android 接入 ​

差异见上文「平台差异说明」。宿主 AndroidManifest.xml 必须去掉首页 Activity 的启动入口，只留插件 alias：

xml
<activity
    android:name="io.dcloud.uniapp.UniAppActivity"
    android:exported="true"
    tools:node="merge">
    <intent-filter tools:node="removeAll">
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

改完后卸载重装。插件 alias：XAppIconDefault / XAppIconSanbu / XAppIconZuoyiqi / XAppIconShuijiao / XAppIconWangwang / XAppIconBlack。

iOS 说明 ​

本插件走静默切换，不弹系统确认框。

HarmonyOS 说明 ​

角标走 notificationManager.setBadgeNumber。本地 app.json5 alternateIcons 从 API 26 才有；上架图标管理需开通 AGC。当前工程 SDK 下切换图标返回 1008。

Web 说明 ​

浏览器不能改操作系统桌面图标，采用标签站点图标及应用WEBICON切换

更新日志 ​

1.0.7（2026-09-09） ​

  • 预置图标改为 6 套：default / sanbu / zuoyiqi / shuijiao / wangwang / black
  • 按各端规范生成 Android mipmap、iOS @2x/@3x、Harmony media、Web 180px 资源

1.0.6（2026-08-17） ​

  • 去掉 iOS showAlert 参数和演示页「用系统弹层切换」入口，切图标只走静默

1.0.5（2026-08-17） ​

  • iOS Info.plist 增加 CFBundleDevelopmentRegion / CFBundleLocalizations / CFBundleAllowMixedLocalizations，系统切图标弹层跟随中文

1.0.4（2026-08-17） ​

  • iOS 默认静默切换图标，不再弹出系统「已更改图标」；需要官方弹层时传 showAlert: true

1.0.3（2026-08-17） ​

  • Android：宿主清单去掉 UniAppActivity 的 LAUNCHER，只留一个 activity-alias，避免桌面出现两个图标、切换只改第二个
  • Android：角标改用可显示通知通道；小米 / 红米 / HyperOS 写入 extraNotification.setMessageCount，不再用会被忽略的静默 LOW 通道

1.0.2（2026-08-17） ​

  • Web：动态图标改为切换标签页 favicon，并更新 Safari apple-touch-icon（主屏幕 / 程序坞大图标）
  • Web：数字角标和小红点改为写在浏览器标签标题上闪烁

1.0.1（2026-08-17） ​

  • 修复 HarmonyOS 编译：catch 不再标注类型；结果类型里的必填 boolean 去掉 @default，避免编成 field!: boolean = false

1.0.0（2026-08-17） ​

  • 新增桌面图标切换：xSetAppIcon / xResetAppIcon / xGetAppIcon / xGetSupportedAppIcons
  • 内置节日 / 促销 / 春节三套图标；系统不允许远程图片作为桌面图标
  • 新增桌面角标：xSetAppBadge / xGetAppBadge / xClearAppBadge
  • 覆盖 Android（activity-alias + 厂商角标）/ iOS（Alternate Icon + Badge）/ HarmonyOS（角标）/ Web（Badging API）
最近更新