应用有新版了,总不能靠群里喊"更新了更新了"吧。之前做应用市场评分是让用户自己去市场找,这个更直接——我在应用里就能检测有没有新版本,弹个窗问用户要不要更新。
更新功能是啥
鸿蒙的 AppGallery Kit 提供了一个更新功能模块,两个 API 搞定:
checkAppUpdate(context)— 检测当前应用在 AppGallery 上有没有新版本showUpdateDialog(context)— 弹出一个系统级的更新对话框,用户点确定就跳应用市场下载
业务流程就三步:应用启动或用户手动检查 → 调用检测接口 → 有更新就弹对话框。
有几个限制条件:
- 必须在真机上跑,模拟器不支持
- 应用得在 AppGallery 上架了才能检测
- 本地版本号要低于应用市场在架版本号
- 签名信息必须一致
所以开发阶段这个功能是测不了的,得等应用上架了才行。但桥接代码可以先写好。
桥接插件
ArkTS 侧代码,跟之前的模式一样:
import { FlutterPlugin, FlutterPluginBinding, MethodCall, MethodChannel, MethodResult } from '@ohos/flutter_ohos';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { updateManager } from '@kit.AppGalleryKit';
interface UpdateCheckResult {
hasUpdate: boolean;
versionName: string;
}
export class AppUpdatePlugin implements FlutterPlugin {
private context: common.UIAbilityContext;
private channel: MethodChannel | null = null;
constructor(ctx: common.UIAbilityContext) {
this.context = ctx;
}
onAttachedToEngine(binding: FlutterPluginBinding): void {
this.channel = new MethodChannel(binding.getBinaryMessenger(), 'com.example/app_update');
this.channel.setMethodCallHandler({
onMethodCall: (call: MethodCall, result: MethodResult) => {
if (call.method === 'checkAppUpdate') {
this.handleCheckAppUpdate(result);
} else if (call.method === 'showUpdateDialog') {
this.handleShowUpdateDialog(result);
} else {
result.notImplemented();
}
}
});
}
private handleCheckAppUpdate(result: MethodResult): void {
try {
updateManager.checkAppUpdate(this.context).then((checkResult) => {
// updateAvailable 是枚举,LATER_VERSION_EXIST=1 表示有新版本
const hasUpdate = checkResult.updateAvailable === updateManager.UpdateAvailableCode.LATER_VERSION_EXIST;
const out: UpdateCheckResult = {
hasUpdate: hasUpdate,
versionName: checkResult.versionName ?? '',
};
console.info('[AppUpdatePlugin] checkAppUpdate hasUpdate=' + hasUpdate
+ ' versionName=' + out.versionName);
result.success(out);
}).catch((err: BusinessError) => {
console.error('[AppUpdatePlugin] checkAppUpdate error: ' + JSON.stringify(err));
result.success({ hasUpdate: false, versionName: '' });
});
} catch (e) {
console.error('[AppUpdatePlugin] checkAppUpdate exception: ' + JSON.stringify(e));
result.success({ hasUpdate: false, versionName: '' });
}
}
private handleShowUpdateDialog(result: MethodResult): void {
try {
updateManager.showUpdateDialog(this.context).then((resultCode) => {
result.success(resultCode);
}).catch((err: BusinessError) => {
result.success(-1);
});
} catch (e) {
result.success(-1);
}
}
}
两个方法都在一个插件里,共用 com.example/app_update 通道。Dart 侧通过 call.method 区分。
CheckUpdateResult 返回两个关键字段:updateAvailable(枚举值,不等于 1 表示有新版本)和 versionName(新版本号)。没有更新说明字段。
CheckUpdateResult 和 UpdateAvailableCode
checkAppUpdate 返回的 CheckUpdateResult 类型长这样:
| 字段 | 类型 | 说明 |
|---|---|---|
| updateAvailable | UpdateAvailableCode | 枚举,LATER_VERSION_EXIST=1 表示有更新 |
| versionName | string | undefined | 新版本号,仅在元服务场景下有值 |
| versionCode | number | undefined | 版本号数值,仅在元服务场景下有值 |
重点是这个 UpdateAvailableCode 枚举——它不是布尔值,下标指向:
| 枚举值 | 值 | 含义 |
|---|---|---|
| LATER_VERSION_NOT_EXIST | 0 | 不存在新版本 |
| LATER_VERSION_EXIST | 1 | 存在新版本 |
所以判断逻辑不是 if (checkResult.updateAvailable) 而是 if (checkResult.updateAvailable === updateManager.UpdateAvailableCode.LATER_VERSION_EXIST)。一开始我写的是 if (checkResult.updateAvailable),结果编译报错——类型不对,ArkTS 不允许隐式类型转换。
versionName 对应的是你在 AppGallery 上架时填的版本号,比如 "1.2.0"。它是可选字段,非元服务场景下可能为空字符串。所以在 Dart 侧做 ?? '' 兜底。
收到结果后怎么处理
检测到有更新之后,一般有几种处理方式:
- 直接弹系统弹窗 — 调用
showUpdateDialog,最省事 - 先展示版本号再弹窗 — 自己用
versionName组装 Flutter 界面,用户看完再弹窗 - 强制更新 — 重大版本更新直接弹窗不准关
方式 1 最常用,一行代码就跳过去了。方式 2 需要你额外写一个 Flutter 的 Dialog 或页面,适合更新说明比较长的情况。方式 3 适合重大版本更新——但鸿蒙的系统弹窗用户是可以按返回取消的,真要强制更新还得在 Dart 侧做限制。

Dart 侧调用
两个方法,一个检测更新一个弹窗:
static const _appUpdateChannel = MethodChannel('com.example/app_update');
static Future<Map<String, dynamic>> checkAppUpdate() async {
try {
final result = await _appUpdateChannel
.invokeMethod<Map<Object?, Object?>>('checkAppUpdate');
if (result == null) return {'hasUpdate': false};
return result.map((k, v) => MapEntry(k.toString(), v));
} catch (_) {
return {'hasUpdate': false};
}
}
static Future<int> showUpdateDialog() async {
try {
final result = await _appUpdateChannel.invokeMethod<int>('showUpdateDialog');
return result ?? -1;
} catch (_) {
return -1;
}
}
Demo 页面两个按钮:检测新版本、弹出更新弹窗。检测到了新版本,第二个按钮才可点。
Future<void> _checkUpdate() async {
final result = await PlatformBridge.checkAppUpdate();
if (result['hasUpdate'] == true) {
_addLog('发现新版本: ${result['versionName']}');
} else {
_addLog('当前已是最新版本');
}
}
Future<void> _showUpdateDialog() async {
final code = await PlatformBridge.showUpdateDialog();
if (code == 0 || code == 1) {
_addLog('更新弹窗已显示 (code=$code)');
}
}
showUpdateDialog 返回的 code 是 ShowUpdateResultCode 枚举:
| 枚举值 | 值 | 含义 |
|---|---|---|
| SHOW_DIALOG_SUCCESS | 0 | 弹窗成功 |
| SHOW_DIALOG_FAILURE | 1 | 弹窗失败 |
| -1 | -1 | 调用异常 |
一开始我理解反了,以为 0 是取消、1 是点击更新。实际是 0 表示弹窗成功(不管用户点了更新还是取消,对话框正常显示就算成功),1 表示弹窗失败(比如应用不在前台)。如果返回 -1,说明是桥接错误或者异常情况。
Demo 完整代码
class _AppUpdateDemoState extends State<AppUpdateDemo> {
final List<String> _logs = [];
Map<String, dynamic>? _checkResult;
bool _hasChecked = false;
Future<void> _checkUpdate() async {
final result = await PlatformBridge.checkAppUpdate();
_hasChecked = true;
_checkResult = result;
if (result['hasUpdate'] == true) {
_addLog('发现新版本: ${result['versionName']}');
} else {
_addLog('当前已是最新版本');
}
}
Future<void> _showUpdateDialog() async {
final code = await PlatformBridge.showUpdateDialog();
if (code == 0 || code == 1) {
_addLog('更新弹窗已显示 (code=$code)');
} else {
_addLog('弹窗失败 (code=$code)');
}
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('应用更新检测'), backgroundColor: Colors.teal),
body: Column(
children: [
Card(
child: Column(
children: [
const Icon(Icons.system_update, size: 64, color: Colors.teal),
Text(_hasChecked && _checkResult?['hasUpdate'] == true
? '发现新版本 ${_checkResult!['versionName']}'
: _hasChecked ? '当前已是最新版本' : '检查 AppGallery 上是否有新版本'),
Row(
children: [
ElevatedButton.icon(
onPressed: _checkUpdate,
icon: const Icon(Icons.search),
label: const Text('检测新版本'),
),
ElevatedButton.icon(
onPressed: _hasChecked ? _showUpdateDialog : null,
icon: const Icon(Icons.download),
label: const Text('弹出更新弹窗'),
),
],
),
],
),
),
Expanded(
child: _logs.isEmpty
? const Center(child: Text('点击按钮测试桥接'))
: ListView.builder(
itemCount: _logs.length,
itemBuilder: (_, i) => Text(_logs[i]),
),
),
],
),
);
}
}
两个按钮并排,检测更新和弹窗。第二个按钮只有检测过之后才可点。

注册插件
跟其他需要 context 的插件一样:
plugins.add(new AppUpdatePlugin(this.context));
目前 EntryAbility 里注册了 12 个插件,接近一半需要传 context:
plugins.add(new UrlLauncherPlugin(this.context));
plugins.add(new SharePlugin(this.context));
plugins.add(new PathProviderPlugin(this.context));
plugins.add(new KeepScreenOnPlugin(this.context));
plugins.add(new AppMarketPlugin(this.context));
plugins.add(new AppUpdatePlugin(this.context));
// 剩下 6 个不需要 context
需要 context 的基本上都是要调用 AbilityKit 或 AppGalleryKit 的 API。
检测流程说明
这里的流程和自动更新不太一样。用户触发的检测是主动的——点一下按钮去 AppGallery 查询版本信息。查询结果只告诉你有没有新版本,不自动下载。
showUpdateDialog 弹出来的是系统级对话框,风格跟 AppGallery 一致。用户点"更新"就跳转到应用市场下载页面,不走你的应用。你不需要管下载进度、安装之类的。
我一开始以为更新弹窗可以自定义 UI,后来发现不行——AppGalleryKit 的弹窗是系统样式,你不能改。如果你想定制更新界面,那就别用 showUpdateDialog,自己根据 checkAppUpdate 的结果写一个 Flutter Dialog 或者 BottomSheet。
官方文档里给的流程是:checkAppUpdate → 如果 updateAvailable === true → 调用 showUpdateDialog。但实际上你可以在中间插一步——检测到更新后,先展示你自己的更新说明页面,用户看完再点"更新"去弹系统窗口。
几个注意的点
kit 依赖。 这个插件用到了 @kit.AppGalleryKit。如果项目里之前没用过这个 kit,需要在 oh-package.json5 里加依赖,或者在 DevEco Studio 里通过"添加 Kit"的方式引入。一般鸿蒙 5.0 以上的项目默认就有。
不支持模拟器。 模拟器上调用 checkAppUpdate 会返回"无法获取内容"的错误。必须用真机调试。
上架后才能测。 本地调试是测不了的,因为 AppGallery 上没有你的版本信息。我一开始在开发机上试了半天,一直返回无更新。后来才意识到——本地的 debug 包跟应用市场上架的正式包签名都不一样,怎么可能匹配上。
版本号对比逻辑。 检测是基于 versionName 做字符串对比还是 versionCode 做数值对比?官方文档里说要"本地安装版本须低于应用市场在架版本才能检查到更新"。实际是通过 bundleName 和签名匹配,然后对比 versionCode。所以如果你只是改了 versionName 没改 versionCode,也检测不到更新。
签名一致性。 这个很关键。检测 API 要求本地安装包和应用市场在架包的签名一致。测试包(debug)用的是 debug 签名,正式包是 release 签名,所以检测不到是正常的。上架后的正式版才能正确检测。
errorInfo 的处理。 CheckUpdateResult 没有 errorInfo 字段。如果出错(网络异常、服务器超时等),Promise 会 reject,走 catch 分支统一返回 { hasUpdate: false }。调试的时候在 ArkTS 日志里看 BusinessError 的 code 就能判断是哪种错误。
oh-package.json5 配置
如果项目里报 '@kit.AppGalleryKit' 导入错误,说明还没添加这个 kit 的依赖。需要在 oh-package.json5 里加上:
{
"dependencies": {
"@kit.AppGalleryKit": "file:${arkArchive}/har/cn/ohos/kit/AppGalleryKit.har"
}
}
不过大部分鸿蒙 5.0 项目在 DevEco Studio 初始化的时候就已经包含了基础 kit。更不容易出错的方式是直接在 DevEco Studio 里:右键项目 → Add Kit → 选择 AppGallery Kit。
添加好之后重新 sync 一下项目,import { updateManager } from '@kit.AppGalleryKit' 就能找到了。
showUpdateDialog 的返回值
showUpdateDialog 返回的是一个 ShowUpdateResultCode 枚举。各值含义:
| 值 | 含义 |
|---|---|
| 0 | 用户取消了更新 |
| 1 | 用户点击了更新,正常跳转 |
| -1 | 调用出错或异常 |
这个返回值可以用来做统计——弹窗成功和弹窗失败的比例。不过用户有没有点击更新,这个没法从这个返回值里判断。如果想做更细的统计,需要自己加一层事件埋点。
还有一个细节:如果本地已经是最新版,调用 showUpdateDialog 会不会弹窗?文档里没明说,但推测会提示"已是最新版本"。
和前面几个桥接的对比
这个插件和前面的应用市场评分桥接有点关联——评分是跳转详情页,更新是检测版本+弹更新窗。区别在于:
- 评分用的是
Want隐式跳转,不依赖 AppGalleryKit - 更新用的是 AppGalleryKit 的
updateManager,需要 kit 依赖
从复杂度看,更新比评分多了检测这一步。评分是一个 startAbility 搞定,更新是两个 API 组合使用。
如果只用一个 showUpdateDialog 不先调用 checkAppUpdate,也能弹窗——检测到有新版本就显示更新按钮,没有就显示"已是最新"。所以如果不需要自己处理版本信息展示,直接弹窗也行。
踩过的坑
坑一:模拟器上测了半天。 当时在模拟器上跑,点检测一直报错"无法获取内容"。我还以为是桥接代码写错了,查了半天 MethodChannel 的通道名对不对。后来看官方文档才注意到"应用市场更新功能不支持模拟器"这一行。换到真机就好了。
坑二:debug 包检测不到更新。 即使真机上了,用 debug 模式跑也检测不到。因为 debug 包的签名跟市场上架的正式包不一样,API 对比的时候就匹配不上。这个问题卡了我一下午,后来我在官方 FAQ 里找到说明——"本地安装版本须和应用市场在架版本签名信息保持一致"。要测试的话得打一个正式签名的包在真机上装一次。
坑三:kit 没引入编译不过。 第一次写 import { updateManager } from '@kit.AppGalleryKit' 的时候编译报错——找不到模块。因为项目之前没用过 AppGalleryKit,需要在 DevEco Studio 的 oh-package.json5 里添加这个 kit 的依赖。我一开始还不确定是哪一步,后来在项目里搜了下其他 kit 的引用才搞明白。
写在最后
应用内更新检测算是基础功能,但桥接到 Flutter 里对用户来说体验提升挺明显的——不需要离开应用去应用市场手动刷更新,直接在应用里点一下就行。
对了,这个功能适合做一个"检查更新"按钮放在设置页里。用户点一下,有更新就弹窗引导他跳应用市场下载,没更新就提示"已是最新"。几行桥接代码,体验提升不小。












































苏公安网备 32011402010933号