补上缺失的拼图:为 uni-app 鸿蒙端实现微信"商家转账确认收款"插件
本文记录一个 UTS 插件从可行性分析、架构设计到真机验证的完整过程:为 uni-app 鸿蒙端(HarmonyOS NEXT)补上微信商家转账用户确认收款(
requestMerchantTransfer)能力。官方插件至今只支持 Android/iOS,而鸿蒙端真正的难点是"微信回跳的回调怎么回到插件里"。文中给出最终方案(UTSHarmony生命周期钩子自动接管)、完整代码与踩坑记录,也包括我因为只翻了文档一处章节就下结论、导致方案绕了一大圈的完整过程。
- 插件地址(DCloud 插件市场):
https://ext.dcloud.net.cn/plugin?id=30839(插件 IDxyyt-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)。这条路官方没铺,需要自己铺。
二、可行性:三个关键前提恰好都成立
动手前先确认了三件事:
- 原生壳工程已内置微信 OpenSDK 。uni-oauth-weixin(微信登录)的传递依赖里带着
@tencent/wechat_open_sdk@1.0.23,翻它的d.ets:OpenBusinessViewReq/OpenBusinessViewResp/WXAPIFactory全都在,且鸿蒙 OpenSDK ≥ 1.0.5 即支持该 API------版本余量充足。 - 微信客户端兼容性明确。官方文档:微信 ≥ 8.0.11.34 可调起确认收款页面,低于此版本无法拉起(可提示升级)。
- 仓内有成熟先例 。
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,仓库地址见开头
如果这篇文章帮你省了时间,欢迎在插件市场点个五星。