更新记录

1.0.0（2026-09-22）

AIGC: ContentProducer: '001191110102MAD55U9H0F10002' ContentPropagator: '001191110102MAD55U9H0F10002' Label: '1' ProduceID: 'b5f1f2ac-8821-4083-af3b-c88f928a8e95' PropagateID: 'b5f1f2ac-8821-4083-af3b-c88f928a8e95' ReservedCode1: '2bf11f8a-d1ed-41be-9984-bd3c2b460066' ReservedCode2: '2bf11f8a-d1ed-41be-9984-bd3c2b460066'

cc-open-appgallery 跳转华为应用市场 UTS 插件使用说明

插件简介

cc-open-appgallery 是一个 HarmonyOS UTS 插件，通过隐式 Want 拉起华为应用市场指定应用的详情页。

适用于 App 版本更新引导、应用推荐等场景：用户检测到新版本后，一键跳转到华为应用市场完成更新。

平台兼容性

环境要求

• HBuilderX >= 4.24.0
• HarmonyOS SDK >= 6.0.0(20)
• uni-app Vue3 项目
• 设备需安装华为应用市场（大多数鸿蒙设备预装）

目录结构

cc-open-appgallery/
├── package.json                    # 插件配置
├── index.js                        # JS 桩文件（非鸿蒙平台模块解析用）
├── index.d.ts                      # TypeScript 类型声明
├── utssdk/
│   ├── interface.uts               # 接口定义（不加密）
│   └── app-harmony/
│       └── index.uts               # 鸿蒙原生实现

API 说明

openAppGallery(bundleName)

拉起华为应用市场指定应用的详情页。

参数：

返回值：Promise<OpenAppGalleryResult>

interface OpenAppGalleryResult {
  success: boolean   // 是否成功拉起
  message: string    // 结果说明
}

示例：

import { openAppGallery } from '@/uni_modules/cc-open-appgallery'

const result = await openAppGallery('com.tencent.mm')
if (result.success) {
  console.log('已打开华为应用市场详情页')
} else {
  console.log('打开失败：' + result.message)
}

实现原理

插件通过鸿蒙隐式 Want 机制拉起华为应用市场：

action: ohos.want.action.appdetail
uri:    store://appgallery.huawei.com/app/detail?id=<bundleName>

这是华为官方文档 FAQ 推荐的拉起应用市场方式。

使用场景

场景 1：App 版本更新引导

// 检测到新版本后，引导用户跳转应用市场更新
// #ifdef APP-HARMONY
import { openAppGallery } from '@/uni_modules/cc-open-appgallery'
// #endif

async function doUpdate() {
  // #ifdef APP-HARMONY
  const result = await openAppGallery('hm.lzt.ct.com')
  if (!result.success) {
    uni.showModal({
      title: '提示',
      content: result.message || '无法打开应用市场，请手动前往华为应用市场更新。',
      showCancel: false
    })
  }
  // #endif

  // #ifdef APP-PLUS
  // 安卓端跳浏览器下载
  plus.runtime.openURL('https://example.com/download/latest.apk')
  // #endif
}

场景 2：关于页面跳转应用市场

// #ifdef APP-HARMONY
import { openAppGallery } from '@/uni_modules/cc-open-appgallery'
// #endif

function openAbout() {
  // #ifdef APP-HARMONY
  openAppGallery('hm.lzt.ct.com')
  // #endif
}

注意事项

1. 设备需安装华为应用市场：大多数鸿蒙设备预装，少数精简版设备可能未安装，插件会返回失败提示
2. 包名需准确：bundleName 必须与华为应用市场上架的应用包名完全一致
3. 条件编译：非鸿蒙平台调用会走 index.js 桩文件，直接返回 { success: false, message: '当前平台不支持' }
4. 无需额外权限：拉起应用市场不需要声明任何系统权限

Demo 工程

桌面 cc-open-appgallery-demo 目录包含完整的使用示例工程，可直接用 HBuilderX 打开运行。

运行步骤：

1. HBuilderX 打开 cc-open-appgallery-demo 目录
2. 运行 → 运行到手机或模拟器 → 鸿蒙（需连接鸿蒙真机或模拟器）
3. 在 demo 页面中输入包名，点击跳转按钮测试

技术实现要点

• 使用 @kit.AbilityKit 的 UIAbilityContext.startAbility 发起隐式 Want
• action 指定为 ohos.want.action.appdetail
• uri 格式为 store://appgallery.huawei.com/app/detail?id=<bundleName>
• 通过 @dcloudio/uni-runtime 的 getAbilityContext 获取当前 Ability 上下文
• 异常捕获完整，失败返回结构化错误信息

平台兼容性

uni-app(5.24)

uni-app x(5.24)

其他