更新记录
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、签名和运行环境配置。上述版本声明不等同于每个版本均已完成真机验证。
安装与接入
- 从 DCloud 插件市场通过 HBuilderX 导入插件到项目。
- 确认项目中存在
uni_modules/ll-app-restart目录。 - 使用
APP-HARMONY条件编译包裹导入与调用,避免其他平台引用未实现的接口。 - 重新编译并运行鸿蒙应用。若使用自定义基座,需将插件编译到基座中;仅热刷新页面不会将新增的原生插件加入已有基座。
插件无需配置 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的说明为准。
使用注意事项
- 先保存,再重启:提前完成表单、配置等数据持久化;异步写入应等待完成后再发起重启。内存变量和未保存的页面状态不会由插件恢复。
- 保持前台和焦点:避免在跳转外部应用、退到后台或系统弹窗导致失焦时发起重启。
- 避免循环重启:不要在
onLaunch、onShow等生命周期中无条件调用。若业务需要启动后重启,应持久化并检查已处理标记。 - 避免重复调用:业务侧应控制重复点击,并在失败时向用户提供手动重新打开应用的提示。
- 更新流程单独处理:如用于资源更新,须先由业务确认安装成功,再调用本插件;插件不保证资源包的兼容性或更新结果。
- 验证完整启动链路:应在目标鸿蒙设备上验证重启后能否正常进入应用、读取已保存的数据,以及失败提示是否符合预期。
常见问题
为什么没有成功回调?
系统重启会结束原应用进程,插件未设计成功回调。需要确认重启后状态时,请在业务中先保存标记,再于下一次应用启动时读取并处理。
可以用来刷新页面吗?
本插件会重启应用进程。仅需切换页面或重新加载页面时,应使用相应的 uni-app 路由或页面更新能力。
重启失败如何排查?
记录 fail 中的 errCode 和 errMsg,结合设备系统版本、HBuilderX 版本及调用时机排查。优先检查应用是否处于前台且具有焦点、是否在主线程调用,以及运行包中是否已编译本插件。错误信息来自系统,不保证为中文。
支持后台静默重启或指定页面启动吗?
不支持后台静默重启,也未提供指定页面、指定其他 Ability 或传入自定义 Want 参数的接口。重新启动后的页面和登录状态由宿主应用的启动逻辑决定。
隐私与依赖说明
基于当前插件源码:
- 不采集、存储或上传个人信息,不发起网络请求。
- 仅在调用时读取当前 UIAbility 的包名、模块名及 Ability 名称,用于构造系统重启请求。
- 不包含广告、统计或其他第三方 SDK。
- 业务侧添加的日志上报、更新服务及数据处理行为应由宿主应用另行说明。
问题反馈
可通过插件市场反馈问题。建议提供插件版本、HBuilderX 版本、项目类型(uni-app / uni-app x)、设备型号、HarmonyOS 版本、复现步骤,以及 fail 回调中的错误码和错误信息。请勿提交账号、令牌等敏感信息。

收藏人数:
购买普通授权版(
试用
赞赏(0)
下载 4
赞赏 0
下载 12777488
赞赏 1960
赞赏
京公网安备:11010802035340号