更新记录

1.0.0（2026-04-11） 下载此版本

初次提交

平台兼容性

uni-app x(5.02)

laoqianjunzi-icon

动态切换桌面icon图标，支持vue2/vue3,ios/android/harmony

动态切换app的桌面icon图标，实现类似双十一、过年时app桌面图标自动变化的效果

配置项目

1. 下载demo示例，将demo里的 nativeResources 文件、AndroidManifest.xml、Info.plist 文件拷贝到自己的项目里（如果已经存在此文件或文件夹请合并内容，合并内容可咨询作者）
2. 替换 nativeResources 下 iOS 和 Android 的图标文件，文件名称不能修改，只替换图片
3. 删除本地基座和手机app，重新自定义基座，使用自定义基座运行

鸿蒙集成步骤

1. 首先开通图标管理服务，并保证应用处于正式上架状态；
2. 在图标管理页面上传应用的个性化图标，上传正方形大小为 216*216px 的图片，格式为 PNG 格式或 WEBP 格式
3. 业务流程：查询动态图标信息(queryIcon) → 切换动态图标(changeIcon) → 恢复默认图标(resetIcon)

注意： iOS 和 Android 当前仅支持3个图标切换，如需支持更多图片切换，请联系作者定制

接口文档

import {
  queryIcon,
  changeIcon,
  resetIcon,
  supportIcon,
  currentIcon
} from "@/uni_modules/laoqianjunzi-icon"

基础使用示例

// 在 data 中定义平台判断和图标名称
data() {

  return {
    title: 'Hello',
    names: ["com.laoqianjunzi.icon1", "com.laoqianjunzi.icon2", "com.laoqianjunzi.icon3"],
    msg: null
  }
},

替换桌面图标icon

有些Android机型切换桌面图片后app会自动切换到后台，所以一般Android里在app后台运行时或关闭app时再切换icon

iOS替换桌面图标时，会弹出系统提示框，为了不弹出这个提示框，请同时集成插件 https://ext.dcloud.net.cn/plugin?name=wrs-uts-replaceappicon-noalert

// 切换图标示例
function switchIcon() {
  var params = {};
  switch (uni.getSystemInfoSync().platform) {
    case 'android': {
      // AndroidManifest.xml，所有的activity-alias名称
      let names = ["com.laoqianjunzi.icon1", "com.laoqianjunzi.icon2", "com.laoqianjunzi.icon3"]
      params.iconName = "com.laoqianjunzi.icon1" // AndroidManifest.xml里要显示的activity-alias名称
      params.names = names
      params.restartSystemLauncher = true; // 是否重启launch,仅支持Android，有些机型需要重启launch后图标才能生效
      break;
    }
    case 'ios': {
      params.iconName = "laoqianjunzi_icon1" // Info.plist里配置的CFBundleAlternateIcons节点下的名称
      break;
    }
    case 'harmonyos': {
      // 业务流程：查询动态图标信息(queryIcon)->切换动态图标(changeIcon)->恢复默认图标(resetIcon)
      queryIcon({
        success: (resp) => {
          let flag = resp.flag
          if(flag) {
            let icons = resp.icons
            let titles = []
            for(let i = 0; i < icons.length; i++) {
              titles.push(icons[i].iconUrl)
            }
            // 显示选择弹窗
            uni.showActionSheet({
              itemList: titles,
              success: (res) => {
                let index = res.tapIndex
                let iconId = icons[index].iconId 
                let params = {}
                params.iconId = iconId
                changeIcon(params, (resp) => {
                  let suc = resp.flag
                  if(suc) {
                    uni.showToast({
                      title: '切换成功',
                      icon: 'success'
                    })
                  } else {
                    uni.showToast({
                      title: "切换图标失败:" + JSON.stringify(resp),
                      icon: 'none'
                    })
                  }
                })
              }
            })
          } else {
            uni.showToast({
              title: "查询动态图标失败:" + JSON.stringify(resp),
              icon: 'none'
            })
          }
        }
      })
      return; // 鸿蒙流程特殊，直接返回
    }
    default:
      break;
  }

  changeIcon(params, (resp) => {
    console.log("切换图标结果:", JSON.stringify(resp))
    if (resp.flag) {
      uni.showToast({
        title: '切换成功',
        icon: 'success'
      })
    } else {
      uni.showToast({
        title: '切换失败: ' + resp.msg,
        icon: 'none'
      })
    }
  });
}

重置为app原本的icon

// 重置图标示例
function resetToDefaultIcon() {
  var params = {};
  if (this.isAndroid) {
    params.names = this.names
  }

  resetIcon(params, (resp) => {
    console.log("重置图标结果:", JSON.stringify(resp))
    if (resp.flag) {
      uni.showToast({
        title: '重置成功',
        icon: 'success'
      })
    } else {
      uni.showToast({
        title: '重置失败: ' + resp.msg,
        icon: 'none'
      })
    }
  })
}

判断是否支持修改桌面icon

// 检测支持情况
function checkSupport() {
  let support = supportIcon()
  if (support) {
    console.warn("当前机型支持修改icon")
    uni.showToast({
      title: "当前机型支持修改icon",
      icon: 'none'
    })
  } else {
    console.warn("当前机型不支持修改icon")
    uni.showToast({
      title: "当前机型不支持修改icon",
      icon: 'none'
    })
  }
}

API 详细说明

supportIcon()

检测当前设备是否支持动态切换图标功能。

function supportIcon(): boolean

返回值：

• true: 当前设备支持切换图标
• false: 当前设备不支持切换图标

平台说明：

• iOS: 通常支持（iOS 10.3+）
• Android: 部分机型支持，需检测
• 鸿蒙: 支持

currentIcon()

获取当前桌面图标的标识符。

function currentIcon(): string | null

返回值：

• string: 当前图标的标识符（iconId 或 iconName）
• null: 无法获取当前图标信息

queryIcon(options: queryOptions)

查询当前可用的图标列表。

interface queryOptions {
  success?: (res: QueryIconSuccess) => void
  fail?: (res: ChangeIconFail) => void
  complete?: (res: any) => void
}

interface QueryIconSuccess {
  flag: boolean           // 查询是否成功
  msg: string | null      // 成功或失败信息
  icons: Array<DynamicIconItem>  // 图标列表
}

interface DynamicIconItem {
  iconUrl: string    // 图标资源地址
  iconId: string     // 图标标识符
  enabled: boolean   // 图标是否可用
}

changeIcon(options: changeOptions)

切换到指定图标。

interface changeOptions {
  iconName?: string | null           // 图标名称（可选）
  iconId?: string | null             // 图标标识符（可选）
  names?: Array<string> | null       // 图标名称数组（可选）
  defaultIconName?: string | null    // 默认图标名称（可选）
  restartSystemLauncher?: boolean    // 是否重启系统启动器（Android）
  success?: (res: ChangeIconResult) => void
  fail?: (res: ChangeIconFail) => void
  complete?: (res: any) => void
}

interface ChangeIconResult {
  flag: boolean           // 切换是否成功
  msg: string | null      // 成功或失败信息
  iconName: string | null // 切换后的图标名称
  iconId: string | null   // 切换后的图标标识符
}

resetIcon(options: resetOptions)

重置为默认图标。

interface resetOptions {
  names?: Array<string> | null       // 图标名称数组（可选）
  defaultIconName?: string | null    // 默认图标名称（可选）
  restartSystemLauncher?: boolean    // 是否重启系统启动器（Android）
  success?: (res: ChangeIconResult) => void
  fail?: (res: ChangeIconFail) => void
  complete?: (res: any) => void
}

错误码说明

平台差异说明

iOS

支持程度： ✅ 良好支持（iOS 10.3+） 特点：

• 支持动态切换图标，无需重启应用
• 需要预先在 Info.plist 中配置备用图标
• 切换效果即时生效
• 支持 supportIcon() 检测

Android

支持程度： ⚠️ 部分支持（因厂商定制差异） 特点：

• 不同厂商设备支持程度不同
• 某些设备切换图标后应用会自动切换到后台
• 建议在应用后台运行时或关闭应用时切换图标
• 部分机型需要重启系统启动器（设置 restartSystemLauncher: true）
• 需要配置 Activity Alias 或使用动态组件方式

鸿蒙（HarmonyOS）

支持程度： ✅ 支持 特点：

• 支持动态切换图标
• 需要相应的权限和资源配置
• 遵循鸿蒙应用开发规范

注意事项

1. 图标资源准备：提前准备好所有备用图标资源，确保图标尺寸符合各平台要求
2. Android 兼容性：某些 Android 机型切换图标后应用会退到后台，建议在合适时机切换
3. iOS 提示框：iOS 切换图标时会弹出系统提示框，如需隐藏可集成相关插件
4. 图标数量限制：iOS 和 Android 当前仅支持3个图标切换，如需更多请联系作者定制
5. 测试建议：使用自定义基座进行测试，删除旧基座和 App 后重新运行

版本信息

• 插件版本： 1.0.10
• 插件类型： UTS 插件
• 更新日期： 2026-04-11
• 适配工程： uni-app / uni-app x

技术支持

如有问题或建议，请联系插件开发者或提交 issue。

温馨提示： 动态切换桌面图标是一项增强用户体验的功能，请合理使用，避免频繁切换造成用户困扰。