HarmonyOS 5 应用拉起系列(二):如何拉起微信小程序

随着鸿蒙生态的不断发展,越来越多开发者希望实现应用间的无缝联动,特别是与微信小程序的交互场景,比如拉起乘车码、城市服务等。这类需求在社区中也屡见不鲜,实际开发过程中更是踩坑不断。

本文将完整分享如何在 HarmonyOS 中实现"拉起微信小程序"的能力,覆盖从申请 AppId、SDK 集成到拉起实现与常见错误排查的全过程。若你尚不清楚 HarmonyOS 中其他拉起方式,可参考本系列第一篇文章。

一、前期准备工作

1. 在微信开放平台申请 AppId 并配置鸿蒙应用信息

要拉起微信小程序,首先需要在微信开放平台申请一个鸿蒙专用的移动应用 ID(AppId),注意:

  • 提交审核前需正确填写应用信息,包括 Bundle Name、签名等;
  • 微信将收取审核费用(海外/国内账号略有不同),审核时间约为 5 个工作日;
  • 没有审核通过的 AppId 无法正常拉起微信能力

2. 集成微信 SDK 到鸿蒙项目中

微信已适配 HarmonyOS 并提供官方 SDK,你可以通过 ohpm 安装:

bash 复制代码
ohpm i @tencent/wechat_open_sdk

项目地址:@tencent/wechat_open_sdk - OHPM 三方库

注意:SDK 目前未依赖 so 库,因此支持在元服务中使用。但请注意,一般的元服务本身无法直接拉起微信应用

3. 配置 module.json5 中的 querySchemes(容易遗漏)

确保在 entry/src/main/module.json5 中声明以下字段:

json 复制代码
"querySchemes": [
  "weixin",
  "wxopensdk"
]

若未配置该字段,会导致系统无法识别 weixin:// 等 Scheme,从而拉起失败。

4. 获取目标微信小程序的原始 ID(userName)

你需要获取目标小程序的"原始 ID",方式如下:

1.在微信中打开目标小程序(例如"乘车码"),点击右上角进入详情页;

2.点击「小程序资料」或「更多信息」;

3.复制"原始 ID",即类似 gh_xxxxxxxx 的字符串

二、实现代码示例:拉起微信小程序

以下是封装后的工具类 WxSdkHelper,用于拉起指定微信小程序:

ts 复制代码
const TAG = 'WeiXinSdkOpenHelper'

export class WxSdkHelper {
  static instance: WxSdkHelper = new WxSdkHelper()
  static isStartNet: boolean = true
  private static readonly WX_BUNDLE_NAME = 'com.tencent.wechat'

  private constructor() {} // 单例模式

  /**
   * 拉起微信小程序
   * @param appId 在微信开放平台申请的鸿蒙应用 AppId
   * @param miniProgramId 小程序原始 ID(userName)
   * @param type 小程序类型(正式、开发、体验)
   */
  async openWxMiniProgram(miniProgramId: string | undefined, appId: string,
    type: MINI_PROGRAM_TYPE = MINI_PROGRAM_TYPE.RELEASE, context?: common.UIAbilityContext): Promise<void> {
    if (!miniProgramId) {
      LogUtil.e(TAG, '拉起失败,小程序 ID 为空')
      return
    }

    if (!this.checkWxInstalled(appId)) {
      LogUtil.w(TAG, '微信未安装,尝试跳转应用商店')
      return
    }

    try {
      let contextP = context ?? getContext() as common.UIAbilityContext
      const wxApi = wxopensdk.WXAPIFactory.createWXAPI(appId)
      const request = new wxopensdk.LaunchMiniProgramReq()
      request.userName = miniProgramId
      request.miniprogramType = type

      const success = await wxApi.sendReq(contextP, request)
      success ? LogUtil.d(TAG, '拉起成功') : LogUtil.e(TAG, '拉起失败')
    } catch (err) {
      LogUtil.e(TAG, '拉起微信小程序异常', err)
    }
  }

  private checkWxInstalled(appId: string): boolean {
    const wxApi = wxopensdk.WXAPIFactory.createWXAPI(appId)
    const installed = wxApi.isWXAppInstalled()
    if (!installed) this.openAppInStore(WxSdkHelper.WX_BUNDLE_NAME)
    return installed
  }

  private openAppInStore(bundleName: string, context?: common.UIAbilityContext): void {
    const want: Want = {
      action: 'ohos.want.action.appdetail',
      uri: `store://appgallery.huawei.com/app/detail?id=${bundleName}`,
    }

    const contextP = context ?? getContext() as common.UIAbilityContext
    contextP.startAbility(want)
      .then(() => LogUtil.d(TAG, '已跳转应用商店'))
      .catch((err: BusinessError) => {
        LogUtil.e(TAG, `跳转应用商店失败: ${err.code} - ${err.message}`, err)
      })
  }
}

enum MINI_PROGRAM_TYPE {
  RELEASE = 0, // 正式版
  DEVELOPMENT = 1, // 开发版
  TRIAL = 2 // 体验版
}

三、常见报错与排查指南

1. 微信登录失败:Bundle ID 校验未通过

  • 原因:应用配置未审核通过或填写信息有误;
  • 解决:
    • 确保微信开放平台 App 状态为"审核通过";
    • 检查 appid + identifier + bundleName 是否一致;
    • 登录平台:微信开放平台 > 管理中心 > 移动应用 > 开发配置。

2. 拉起失败:APP_ID 或 Identifier 不一致

  • 原因:
    • 调用 createWXAPI 时使用了错误的 AppId
    • 微信后台配置的 Identifier 与实际应用不匹配;
  • 检查:
    • 是否将小程序的 AppId 误用为移动应用 AppId
    • IDE 自动生成的调试签名是否与实际上传一致(建议单独申请测试用 AppId)。

结语

拉起微信小程序是 HarmonyOS 应用常见的第三方能力接入场景,但涉及平台之间的权限与校验较多,建议开发者在正式开发前先完成微信开放平台的审核流程,并尽量封装通用组件,减少重复踩坑。

如果你觉得这篇文章对你有帮助,欢迎关注本系列后续内容,我们还将介绍:

  • 拉起支付宝支付
  • ArkWeb拉起支付宝支付
  • 拉起地图导航类应用等
相关推荐
啥都不会的码仔2 小时前
鸿蒙ArkTS日期时间处理:全面解析DateUtil工具类
harmonyos·arkts
AORO20255 小时前
三防平板电脑是什么?这款三防平板支持红外测温!
5g·安全·智能手机·电脑·harmonyos
AlbertZein5 小时前
HarmonyOS 5 一杯冰美式的时间 -- MVVM?
harmonyos
zhanshuo18 小时前
HarmonyOS 多屏适配最佳实践:基于 ArkUI 的响应式 UI 方案
harmonyos
zhanshuo18 小时前
玩转 ArkUI 拖拽功能:5 分钟搞定拖放交互与场景实战
harmonyos
shenshizhong1 天前
鸿蒙南向开发 编写一个简单子系统
前端·harmonyos
HarmonyOS_SDK1 天前
一碰即传,重构跨设备文件分享体验
harmonyos
zhanshuo2 天前
让鸿蒙应用飞起来!ArkUI 图形渲染性能优化全攻略
harmonyos
zhanshuo2 天前
在 ArkUI 中实现丝滑嵌套滚动:让你的页面像抖音一样顺滑
harmonyos