更新记录

1.0.0(2026-11-20)

  • 提供鸿蒙应用重启接口 restartApp(options),基于系统 ApplicationContext.restartApp 实现。
  • 自动读取当前 UIAbility 信息,构造重启目标。
  • 提供必填的 fail 回调,返回系统异常的原始错误码与错误信息。
  • 补充平台兼容性、安装接入、uni-app / uni-app x 调用示例、API、使用限制及隐私说明。

平台兼容性

uni-app(4.75)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
- - - - - - - - 5.0.0
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
- - - - - - - - - - - -

uni-app x(4.75)

Chrome Safari Android iOS 鸿蒙 微信小程序
- - - - 5.0.0 -

ll-app-restart

鸿蒙应用重启 UTS 插件,适用于 uni-app / uni-app x 的 HarmonyOS 应用。通过鸿蒙原生 ApplicationContext.restartApp(want) 重启当前应用,可用于需要重新启动应用才能生效的配置变更、资源更新完成后的重启等场景。

功能特点

  • 调用鸿蒙系统应用重启能力,重启应用进程。
  • 自动从当前 UIAbility 上下文获取包名、模块名及 Ability 名称,无需手动填写。
  • 重启请求发生异常时,通过 fail 回调返回原始错误码和错误信息。
  • 无第三方 SDK 依赖,无需初始化。

本插件只负责发起应用重启,不提供更新检查、资源包下载、安装或页面状态恢复功能。

平台兼容性

平台 支持情况
uni-app 鸿蒙 App 支持
uni-app x 鸿蒙 App 支持
Android / iOS 未实现
Web / 各类小程序 未实现

环境要求:

  • HarmonyOS 5.0.0 及以上,原生重启接口要求 API 12 及以上。
  • 插件 package.json 声明的引擎版本为:HBuilderX ^4.0、uni-app ^4.75、uni-app x ^4.75。
  • 实际开发应使用支持对应框架鸿蒙构建的 HBuilderX 版本,并完成鸿蒙 SDK、签名和运行环境配置。上述版本声明不等同于每个版本均已完成真机验证。

安装与接入

  1. 从 DCloud 插件市场通过 HBuilderX 导入插件到项目。
  2. 确认项目中存在 uni_modules/ll-app-restart 目录。
  3. 使用 APP-HARMONY 条件编译包裹导入与调用,避免其他平台引用未实现的接口。
  4. 重新编译并运行鸿蒙应用。若使用自定义基座,需将插件编译到基座中;仅热刷新页面不会将新增的原生插件加入已有基座。

插件无需配置 AppKey、包名、URL Scheme 或第三方 SDK,也未声明额外权限。宿主应用仍需完成正常的鸿蒙应用构建和签名配置。

快速开始

以下为 uni-app Vue 页面示例,用户确认后发起重启。请在确认前完成需要持久化的数据保存。

<template>
  <view>
    <!-- #ifdef APP-HARMONY -->
    <button @click="confirmRestart">重启应用</button>
    <!-- #endif -->
  </view>
</template>

<script>
// #ifdef APP-HARMONY
import { restartApp } from '@/uni_modules/ll-app-restart'
// #endif

export default {
  methods: {
    confirmRestart() {
      // #ifdef APP-HARMONY
      uni.showModal({
        title: '重启应用',
        content: '请确认数据已保存,是否立即重启应用?',
        confirmText: '立即重启',
        success: (res) => {
          if (!res.confirm) return

          restartApp({
            fail: (error) => {
              console.error('[ll-app-restart]', error.errCode, error.errMsg)
              uni.showModal({
                title: '重启失败',
                content: '请退出应用后手动重新打开。',
                showCancel: false
              })
            }
          })
        }
      })
      // #endif
    }
  }
}
</script>

uni-app x 可在 .uvue 页面的 <script setup lang="uts"> 中按以下方式调用,再将 handleRestart 绑定到按钮点击事件:

// #ifdef APP-HARMONY
import { restartApp } from '@/uni_modules/ll-app-restart'

function handleRestart() : void {
  restartApp({
    fail: (error) => {
      console.error('[ll-app-restart]', error.errCode, error.errMsg)
      uni.showModal({
        title: '重启失败',
        content: '请退出应用后手动重新打开。',
        showCancel: false
      })
    }
  })
}
// #endif

API 说明

restartApp(options: RestartAppOptions): void

发起当前应用重启请求。插件使用当前 UIAbility 的 bundleName、moduleName、name 构建 Want,交给系统执行重启。不接受自定义启动目标或附加启动参数。

必须在应用处于前台、具有焦点时从主线程调用,建议由页面按钮等用户交互触发。请勿在后台任务、Worker 或应用失焦时调用。

RestartAppOptions

属性 类型 必填 说明
fail (error: RestartAppFail) => void 是 获取上下文或发起系统重启请求时发生异常的回调

RestartAppFail

属性 类型 说明
errCode number \| null 系统异常的原始 code;未提供错误码时为 null
errMsg string 系统异常的原始 message,插件不做翻译

返回值与回调约定

  • 返回值为 void,不返回 Promise。
  • options 和 options.fail 均为必填,请勿使用 restartApp() 无参调用。
  • 不提供 success、complete 回调。成功重启后原进程结束,不应依赖调用后的代码完成保存、上报或其他重要操作。
  • fail 只报告调用过程中捕获到的异常,未触发 fail 不代表应用已经完成重新启动。
  • 插件未定义自有错误码,具体错误含义以当前鸿蒙 SDK 对 ApplicationContext.restartApp 的说明为准。

使用注意事项

  1. 先保存,再重启:提前完成表单、配置等数据持久化;异步写入应等待完成后再发起重启。内存变量和未保存的页面状态不会由插件恢复。
  2. 保持前台和焦点:避免在跳转外部应用、退到后台或系统弹窗导致失焦时发起重启。
  3. 避免循环重启:不要在 onLaunch、onShow 等生命周期中无条件调用。若业务需要启动后重启,应持久化并检查已处理标记。
  4. 避免重复调用:业务侧应控制重复点击,并在失败时向用户提供手动重新打开应用的提示。
  5. 更新流程单独处理:如用于资源更新,须先由业务确认安装成功,再调用本插件;插件不保证资源包的兼容性或更新结果。
  6. 验证完整启动链路:应在目标鸿蒙设备上验证重启后能否正常进入应用、读取已保存的数据,以及失败提示是否符合预期。

常见问题

为什么没有成功回调?

系统重启会结束原应用进程,插件未设计成功回调。需要确认重启后状态时,请在业务中先保存标记,再于下一次应用启动时读取并处理。

可以用来刷新页面吗?

本插件会重启应用进程。仅需切换页面或重新加载页面时,应使用相应的 uni-app 路由或页面更新能力。

重启失败如何排查?

记录 fail 中的 errCode 和 errMsg,结合设备系统版本、HBuilderX 版本及调用时机排查。优先检查应用是否处于前台且具有焦点、是否在主线程调用,以及运行包中是否已编译本插件。错误信息来自系统,不保证为中文。

支持后台静默重启或指定页面启动吗?

不支持后台静默重启,也未提供指定页面、指定其他 Ability 或传入自定义 Want 参数的接口。重新启动后的页面和登录状态由宿主应用的启动逻辑决定。

隐私与依赖说明

基于当前插件源码:

  • 不采集、存储或上传个人信息,不发起网络请求。
  • 仅在调用时读取当前 UIAbility 的包名、模块名及 Ability 名称,用于构造系统重启请求。
  • 不包含广告、统计或其他第三方 SDK。
  • 业务侧添加的日志上报、更新服务及数据处理行为应由宿主应用另行说明。

问题反馈

可通过插件市场反馈问题。建议提供插件版本、HBuilderX 版本、项目类型(uni-app / uni-app x)、设备型号、HarmonyOS 版本、复现步骤,以及 fail 回调中的错误码和错误信息。请勿提交账号、令牌等敏感信息。

隐私、权限声明

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

无

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

无

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

无

暂无用户评论。