uni-app 鸿蒙端提现点不动?我用 UTS 插件补上了微信"确认收款"

补上缺失的拼图:为 uni-app 鸿蒙端实现微信"商家转账确认收款"插件

本文记录一个 UTS 插件从可行性分析、架构设计到真机验证的完整过程:为 uni-app 鸿蒙端(HarmonyOS NEXT)补上微信商家转账用户确认收款(requestMerchantTransfer)能力。官方插件至今只支持 Android/iOS,而鸿蒙端真正的难点是"微信回跳的回调怎么回到插件里"。文中给出最终方案(UTSHarmony 生命周期钩子自动接管)、完整代码与踩坑记录,也包括我因为只翻了文档一处章节就下结论、导致方案绕了一大圈的完整过程。

  • 插件地址(DCloud 插件市场):https://ext.dcloud.net.cn/plugin?id=30839(插件 ID xyyt-wxmerchanttransfer,1.0.0 已发布)
  • 源码 / demo 工程:https://github.com/xyytwz/uni-wxmerchanttransfer,仓库根本身就是一个 uni-app cli demo 工程(vue3)

一、问题:鸿蒙端点"领取",一点反应都没有

业务场景很常见:用户在 App 内领取推广佣金,后端生成转账单据(状态 WAIT_USER_CONFIRM),前端调起微信"确认收款"页面,用户在微信里点确认,钱从商户零钱到用户零钱。

现有代码的条件编译分支是这样的:

ts 复制代码
// #ifdef APP-PLUS
// Android/iOS:UTS 插件 uni-requestMerchantTransfer(官方实现)
// #endif
// #ifdef MP-WEIXIN
wx.requestMerchantTransfer(...)
// #endif
// #ifdef H5
// toast「该客户端暂不支持领取」
// #endif

鸿蒙端(APP-HARMONY)没有任何分支 。由于 APP-HARMONY 与 APP-PLUS 是并列关系(不是包含),整段领取逻辑在鸿蒙编译时被剔除。点击"领取"后:loading 状态静默开始、三个分支全不命中、endLoading 永不执行 → loading 永久为 true → 后续点击全部被防重检查静默吞掉。表现为按钮完全无效,且无法通过重试恢复。

查官方 uni-requestMerchantTransfer 插件的 package.json:

json 复制代码
"app": {
  "js": false, "kotlin": true, "swift": true,
  "arkts": false    // ← 鸿蒙端:无实现
}

arkts: false------官方只实现了 Android(kotlin)和 iOS(swift)。这条路官方没铺,需要自己铺。

二、可行性:三个关键前提恰好都成立

动手前先确认了三件事:

  1. 原生壳工程已内置微信 OpenSDK 。uni-oauth-weixin(微信登录)的传递依赖里带着 @tencent/wechat_open_sdk@1.0.23,翻它的 d.ets:OpenBusinessViewReq / OpenBusinessViewResp / WXAPIFactory 全都在,且鸿蒙 OpenSDK ≥ 1.0.5 即支持该 API------版本余量充足。
  2. 微信客户端兼容性明确。官方文档:微信 ≥ 8.0.11.34 可调起确认收款页面,低于此版本无法拉起(可提示升级)。
  3. 仓内有成熟先例 。launchWxMiniProgram(拉起微信小程序支付)已经打通了"原生 Reflect.set 注入 uni 命名空间 + WXApi.handleWant 回调分发 + 缓存供 JS 轮询"的完整链路,照搬模式即可。

结论:可行,且工作量可控。

三、真正的拦路虎:回调怎么回到插件里(以及我的一个误判)

如果做成普通 UTS 插件,最大的问题是回调怎么回来。

微信确认收款完成后,微信会拉回宿主 App,回跳 Want 进入 UIAbility 的 onCreate(冷启)或 onNewWant(热启)。在 Android/iOS 的 UTS 插件体系里,插件可以用生命周期代理拦截:

  • iOS:UTSiOSHookProxy 协议
  • Android:UTSAndroidHookProxy 接口

我翻 UTS 插件官方文档,鸿蒙平台章节明确写着------"不涉及此章节内容"。于是我下了结论:鸿蒙 UTS 插件收不到 Want,回调链路无法在插件内闭环,这大概也是官方插件鸿蒙端一直空缺的深层原因。

第一版就是照这个结论做的:插件导出 handleWeChatWant(want),宿主在自己的 EntryAbility.onCreate / onNewWant 里转发。方案能跑,真机也验过了。

但这个结论是错的。

临上架前我复核文档,发现 UTSHarmony 命名空间下明明白白摆着两个 API:

API 签名 uni-app HarmonyOS UTS 插件
onAppAbilityCreate (want: Want, launchParam: AbilityConstant.LaunchParam) => void 4.31
onAppAbilityNewWant 同上 4.31

插件完全可以自己监听宿主 EntryAbility 生命周期、自己拿到 Want。 onCreate 管冷启动回跳,onNewWant 管应用存活时的回跳,两个加起来正好覆盖微信回跳的全部场景。

错在哪:HookProxy 那一章讲的是"插件的应用生命周期代理机制",鸿蒙章节确实不涉及它------但鸿蒙走的是另一套 API(UTSHarmony.*),我没去检索那个命名空间,就把"这一章没提"读成了"这个能力不存在"。

修正后的链路
复制代码
JS 页面 requestMerchantTransfer({mchId, appId, package})
  └─ WXAPIFactory.createWXAPI(appId).sendReq(context, OpenBusinessViewReq)
       query = mchId=xxx&appId=xxx&package=<encodeURIComponent(package_info)>
       → 拉起微信确认收款页
            ↓ 用户确认/取消,微信拉回宿主
宿主 EntryAbility(DCloud 生成的即可,无需改)
  └─ UTSHarmony.onAppAbilityCreate / onAppAbilityNewWant   ← 插件自己注册
       └─ WXApi.handleWant(want, 插件的 handler)
            └─ onResp: instanceof OpenBusinessViewResp
                 && businessType === 'requestMerchantTransfer'
                 → 解析 extMsg {"result":"success|fail|cancel"}
                 → 一次性回调 onMerchantTransferResult(cb)
                 → 同时写入缓存(getLastMerchantTransferResult 轮询备用)

对使用者来说这个修正的差别是决定性的。需要改原生 EntryAbility 的方案,对 HBuilderX 工程并不友好:那份 Ability 由工具链生成,要改就得把它放进项目根目录的 harmony-configs 里整体覆盖(目录内文件是原样覆盖,必须提供完整文件;而且 manifest.json 的鸿蒙配置优先级还高于 harmony-configs,多余文件会干扰构建)。这是一条只有踩过坑的人才知道的进阶路径,不该成为一个插件的默认前提。自动接管后,宿主只剩 module.json5 的两项声明:querySchemes(管拉起)与 abilities[].skills[].actions 里的 wxentity.action.open(管回跳)。

顺着运行时源码看,这个机制其实没有悬念:HBuilderX 生成的 EntryAbility 都写着 extends UniEntryAbility,并在 onCreate / onNewWant 里调用 super.*;而 @dcloudio/uni-app-runtime 的 UniEntryAbility 内部就是两行事件广播------appAbilityEmitter.emit('create', want, launchParam) 和 appAbilityEmitter.emit('newWant', want, launchParam),UTSHarmony.onAppAbility* 订阅的正是这两个事件。

handleWeChatWant 我保留了,降级为离线打包 / 自维护原生工程的可选路径,并在文档里注明不要与自动接管叠加。

还有一个必须单独处理的分场景:冷启动回跳

自动接管后剩一个坑:用户长时间停在微信确认收款页、宿主进程已被系统回收,此时回跳走 onCreate,而插件从没被调起过,内部还没有 WXApi 实例(createWXAPI 需要 appId,而 Want 里并不保证能拿到它)。

做法是两件事:

  • 提供 setMerchantTransferAppId(appId),宿主在 App.vue onLaunch 调一次,冷启动回跳即可正常分发;
  • 拿不到实例时把 Want 暂存 ,等下一次 requestMerchantTransfer 或 setMerchantTransferAppId 时补投,不直接丢弃。

一个自然的担心:宿主同时集成微信登录(uni-oauth-weixin),两方都调 WXApi.handleWant(want, 各自的 handler) 会不会冲突?不会------handleWant 是"解析 Want 后回调传入的 handler",各家 handler 各自处理认识的 resp 类型(登录处理 SendAuth.Resp,本插件只认 OpenBusinessViewResp 且核对 businessType),互不干扰。实测共存正常。

四、API 设计:对齐官方 + 一个增强

调起字段与官方 uni.requestMerchantTransfer 完全对齐(mchId / appId / package / openId / subAppId / subMchId / success / fail / complete),方便从官方插件迁移。在此之上做了一个官方没有的增强 ------官方的 success 仅代表"请求发送成功",用户在微信里到底确认没确认,官方插件是不回传的(Android/iOS 上宿主要自己去微信回调里捞)。

本插件把它变成了一等公民:

ts 复制代码
// 1) 注册一次性确认结果回调(触发后自动注销)
onMerchantTransferResult((res) => {
  // res.result: 'success' | 'fail' | 'cancel'
  // res.errMsg: 微信回传 extMsg 原文,如 {"result":"success"}
})

// 2) 调起(字段与官方一致)
requestMerchantTransfer({
  mchId, appId, package,
  success: () => { /* 页面拉起成功 */ },
  fail: (res) => { /* 未装微信/版本过低/发送失败 */ }
})

// 3) 不想用回调也有轮询式 API
const r = getLastMerchantTransferResult()   // 无结果返回 null

result 语义必须说清楚(微信官方定义):success 仅表示微信确认收款页面展示成功,不代表用户确认成功、更不代表资金到账。业务侧请以刷新后的订单/列表接口为准。

五、实现要点

5.1 组包:query 三参数 + UrlEncode
ts 复制代码
const req = new wxopensdk.OpenBusinessViewReq()
req.businessType = 'requestMerchantTransfer'
req.query = 'mchId=' + encodeURIComponent(options.mchId)
  + '&package=' + encodeURIComponent(options.package)
  + '&appId=' + encodeURIComponent(options.appId)
await wxApi.sendReq(context, req)   // SendReqResultWrap = boolean | Promise<boolean>

package 的值是后端转账单据应答中的 package_info,必须 UrlEncode(里面有特殊字符)。

5.2 回调分发:instanceof + businessType 双重核对
ts 复制代码
class TransferEventHandler implements wxopensdk.WXApiEventHandler {
  onResp(resp: wxopensdk.BaseResp): void {
    if (resp instanceof wxopensdk.OpenBusinessViewResp) {
      const r = resp as wxopensdk.OpenBusinessViewResp
      if (r.businessType === 'requestMerchantTransfer') {
        // 解析 r.extMsg → 回调 + 缓存
      }
    }
  }
}
5.3 extMsg 解析:刻意避开 JSON.parse

extMsg 是 {"result":"success|fail|cancel"} 格式的 JSON 字符串。在 ArkTS 严格模式下 JSON.parse 的类型处理有坑(返回 any,转 Record 再取值,类型链路很不舒服)。由于取值域是固定的三个字符串,直接用字符串特征判断更稳:

ts 复制代码
if (extMsg.indexOf('"success"') != -1) result = 'success'
else if (extMsg.indexOf('"cancel"') != -1) result = 'cancel'
else result = 'fail'

errMsg 透传原始 extMsg,业务侧想自己解析也留了后路。零 JSON 依赖,编译期零风险。

六、集成:一处宿主配置(两项声明)+ 三行业务代码

插件侧不需要任何配置(依赖声明在插件 config.json 里,由工具链带入 ohpm)。宿主需要改的文件也只有一个 entry/src/main/module.json5,但里面是两项声明,缺一不可:

① 拉起 + 回跳两项声明:

json5 复制代码
"module": {
  // 管「拉起」:允许 bundleManager.canOpenLink("weixin://") 查询微信是否安装
  "querySchemes": ["weixin"],
  // 管「回跳」:actions 不在 module 这一层,必须嵌在 abilities[].skills[] 里
  "abilities": [
    {
      "name": "EntryAbility",
      "skills": [
        {
          "actions": ["action.system.home", "wxentity.action.open"]
        }
      ]
    }
  ]
}

两条通道各自失败的现象完全不同,而且很容易归错因:缺 querySchemes 时,微信 SDK 的 isWXAppInstalled() 会在 canOpenLink 抛 BusinessError(实测 17700056)后把它吞成 false,看上去像"用户没装微信";缺 wxentity.action.open 时拉起完全正常 (确认收款页照样打开),但回跳的 Want 路由不回宿主,确认结果永远取不到。两项都编译进 HAP,改完必须重新构建并安装,WGT 热更新 / 替换 www 无效。

②(可选)冷启动兜底 ,App.vue 的 onLaunch 里预配一次 appId:

ts 复制代码
// #ifdef APP-HARMONY
import { setMerchantTransferAppId } from '@/uni_modules/xyyt-wxmerchanttransfer'
setMerchantTransferAppId('wxYourAppId')
// #endif

③ 页面调用(vue3 页面,条件编译包裹):

ts 复制代码
// #ifdef APP-HARMONY
import { requestMerchantTransfer, onMerchantTransferResult } from '@/uni_modules/xyyt-wxmerchanttransfer'
// #endif

页面侧 import 用插件根路径 ,不要直接 import '.../utssdk/app-harmony/index.uts'(原因见踩坑 2)。

附:自维护原生工程的可选转发

离线打包 / 自己持有 EntryAbility 源文件的工程,可以显式转发而不依赖钩子(与自动接管二选一,勿叠加):

ets 复制代码
import { handleWeChatWant } from '@uni_modules/xyyt-wxmerchanttransfer'

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  handleWeChatWant(want)
  super.onCreate(want, launchParam)
}

原生工程内引用 UTS 插件编译产物 ,用模块名 @uni_modules/<插件id全小写>(uni cli 会在鸿蒙工程内生成产物与注册代码),不要用插件源码的相对路径------原生工程里根本没有 uts 源码。

七、踩坑记录(都是真金白银的时间)

坑 1:arkts-no-any-unknown。 ArkTS 严格模式不允许推断出的 any。const existing = Reflect.get(uniObj, key) 直接编译失败,必须显式标注:

ts 复制代码
const existing: Object | undefined = Reflect.get(uniObj, key)

坑 2:页面直接 import utssdk/app-harmony/index.uts 导致 Rollup 解析失败。 vue3 页面如果绕过插件根导入、直接引平台实现文件,Rollup 会尝试解析其中的 @tencent/wechat_open_sdk(ohpm 包)而失败:

复制代码
[vite]: Rollup failed to resolve import "@tencent/wechat_open_sdk" ...

正确姿势:import ... from '@/uni_modules/<插件id>',让 uni-uts-v1 按平台路由。这个坑官方文档的 uni-app-x 示例容易误导人(它写的是平台路径)。

坑 3:hilog 抓不到 native 模块日志。 打包后想看原生注册日志,hilog -x 里翻不到(域过滤/轮转原因未深究)。更可靠的取证方式:解包 HAP(Expand-Archive),在 ets/modules.abc 字节码里直接搜字符串常量------uni-merchant-transfer、requestMerchantTransfer、OpenBusinessViewReq 全部命中,确认新代码已编进包。

坑 4:hdc install -r 更新不了 JS 产物。 DCloud 运行时首启会把 www 解压到应用私有目录,覆盖安装不清私有目录副本,改动"看起来没生效"。必须 uninstall 后 install(代价是清应用数据)。

坑 5:success 语义误解。 调起成功 ≠ 确认成功 ≠ 到账。三个概念,三个不同的确认时机(sendReq 返回值 / extMsg 回调 / 列表接口),别混为一谈。

坑 6:只翻了一处文档章节,就把方案做重了。 即第三节那个误判。我根据 UTS 插件文档 HookProxy 章节里"鸿蒙不涉及"这句话,断定插件收不到 Want,据此设计了"宿主改 EntryAbility 转发"的方案,并一路做到了文档、demo 和原生集成。临上架前复核才发现 UTSHarmony.onAppAbilityCreate / onAppAbilityNewWant 早就存在(4.31 起,uni-app 的 UTS 插件同样可用)。

教训很具体:查平台能力边界时,UTSHarmony / UTSAndroid / UTSiOS 三个平台命名空间的 API 列表都得过一遍,"某一章没提"不等于"平台没这个能力"。这个错误的讨厌之处在于它不会报错------第一版方案能编译、能跑通真机,代价是把插件适用面从"所有鸿蒙工程"缩到了"只有能改原生的工程",属于那种没把全链路跑完就看不出来的哑病。

八、验证

  • uni build -p app-harmony 通过,且 cli 阶段即完成 uts → ets 编译(ArkTS 语法有效性在构建期就被验证)
  • 自动接管在编译产物层得到确认:生成的 index.ets 里 import { UTSHarmony } from "@dcloudio/uni-app-runtime"、两个钩子调用与顶层 installAbilityHooks() 均在------这也反向证明 UTSHarmony 在 uni-app 的 UTS 运行时里确实导出
  • H5 / Android 产物递归扫描插件 API 字符串 0 命中------条件编译隔离干净
  • 真机(HarmonyOS NEXT + 微信 8.0.x):点"领取"→ 拉起微信确认收款页 → 确认后回跳 → 回调触发 → 列表刷新,全链路通过。注意这条结论来自原生直连 / 宿主转发路径
  • UTSHarmony 自动接管的真机回归已完成:2026-11-18 在独立的 uni-app cli 工程(vue3,@dcloudio/* 锁定 3.0.0-5020620260917001,生成的鸿蒙工程为 5.0.1(13))里,宿主原生零改动 ------ 调起确认收款页 → 在微信侧取消并回跳 → onMerchantTransferResult 与 getLastMerchantTransferResult() 都拿到 {"result":"cancel"},证明插件确实能自己收到回跳 Want
  • 仍未闭环的一项:onCreate 冷启动回跳没有真机结论。setMerchantTransferAppId 是按机制推导出来的兜底,插件市场的 changelog 里也如实标注了"暂无真机结论",没有替它许诺可用性
  • API 档位实测覆盖两档:5.0.0(12) 与 5.0.1(13) 都真机跑过。市场表单「平台兼容性」按依赖包声明填 API 12(@tencent/wechat_open_sdk@1.0.23 与 @dcloudio/uni-app-runtime 的 oh-package.json5 均为 compatibleSdkVersion: 12),而不是按"我手边那台机器"填

九、结语

这次最大的收获不是"实现了官方缺失的能力",而是被自己上了一课:"文档某一章没写"和"平台没有这个能力"是两件完全不同的事。如果按第一版方案就发布,这个插件在大多数 HBuilderX 用户手里就是个装得上、跑不通的摆设------而且文档写得越自信,用户越不可能想到问题出在插件的设计前提上。

鸿蒙生态的第三方 SDK 适配仍在早期,很多"缺位"未必是技术不可行,也可能只是像我这样先在文档检索上给自己判了死刑。下手前多花二十分钟把平台命名空间翻完,比事后写一份详尽的"集成注意事项"便宜得多。

插件地址:https://ext.dcloud.net.cn/plugin?id=30839

配套 demo:插件仓库根(uni-app cli 工程)内 src/pages/index/index.vue,仓库地址见开头

如果这篇文章帮你省了时间,欢迎在插件市场点个五星。

相关推荐
wuxianda10301 小时前
苹果 App 上架 4.3(a) 问题解决方案(适用 uniapp、Objective-C、Swift、Flutter 等项目)
uni-app·objective-c·swift
GitCode官方12 小时前
开源鸿蒙跨平台直播|AI 时代,用 cj-tauri 开发鸿蒙 PC 应用
人工智能·华为·harmonyos·atomgit
程序猿追14 小时前
鸿蒙 PC 用 Tauri 做本地查找,怎样让慢请求给新请求让路
华为·状态模式·harmonyos
程序猿追17 小时前
鸿蒙 PC 用 Ionic 做巡检目录,缩窄窗口后草稿还在吗
华为·harmonyos
jianqiang.xue18 小时前
1颗NPU分时复用:鸿蒙把轻AI塞进了MCU
人工智能·单片机·mcu·嵌入式·harmonyos·鸿蒙·端侧ai
程序猿追21 小时前
鸿蒙 PC 用 Tauri 迁移配置文件,先保留旧版再写新版
华为·harmonyos
码间留白2 天前
AI 给的两个方案都被我否了:把 startIcon 与启动遮罩做成同一张图,鸿蒙 APP 冷启动零白屏
性能优化·uni-app·ai编程·harmonyos
二流小码农2 天前
鸿蒙开发:证书只能创建3个,第4个应用怎么办
android·ios·harmonyos
anyup2 天前
自带 uni-app x 页面级能力,uView Pro X 8 个开箱即用的工具函数
前端·vue.js·uni-app