更新记录
1.0.0(2026-11-18) 下载此版本
首个版本,聚焦 uni-app 鸿蒙端(HarmonyOS NEXT)微信商家转账/提现的「用户确认收款」环节。
- 调起微信确认收款页面,字段与官方 uni.requestMerchantTransfer 完全一致(mchId / appId / package / openId / subAppId / subMchId),可直接作为鸿蒙分支替换使用
- 回传用户确认结果(success / fail / cancel):一次性回调 onMerchantTransferResult + 轮询式 getLastMerchantTransferResult,补齐官方插件在鸿蒙端缺失的能力
- 微信回跳 Want 由插件内部 UTSHarmony 生命周期钩子自动接管,宿主无需修改原生代码(需 HBuilderX / uni-app 编译工具链 ≥ 4.31)
- 宿主必配两项,缺一不可:module.querySchemes 含 "weixin"(管拉起)、abilities[].skills[].actions 含 "wxentity.action.open"(管回跳)
- 拉起失败自动分流成因:querySchemes 未配置时明确提示并给出修改位置,不再误报「未安装微信」
- 冷启动兜底 setMerchantTransferAppId(appId);自维护原生工程可用 handleWeChatWant(want) 显式转发
- 日志不输出 package_info / openId 等凭据
- 依赖 @tencent/wechat_open_sdk 1.0.23,要求微信客户端 ≥ 8.0.11.34
- 真机验证:HarmonyOS NEXT + uni-app vue3,微信侧取消回跳全链路已跑通(onNewWant 路径);onCreate 冷启动回跳暂无真机结论
- 范围:仅覆盖「用户确认收款」环节,发起转账仍需后端调用微信支付商家转账接口
平台兼容性
uni-app(4.31)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| × | √ | × | × | × | × | × | × | API 12 |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| × | × | × | × | × | × | × | × | × | × | × | × |
xyyt-wxmerchanttransfer
鸿蒙(HarmonyOS NEXT)端微信商家转账 / 提现的用户确认收款插件:调起微信确认收款页面(requestMerchantTransfer),并回传用户确认结果。
官方插件 uni-requestMerchantTransfer 目前只实现了 Android/iOS(鸿蒙端为 -),本插件补位鸿蒙实现;调起字段与官方 API 保持一致,可直接作为鸿蒙分支替换使用。
微信回跳的 Want 由插件内部通过 UTSHarmony 生命周期钩子自动接管,宿主无需修改任何原生代码,但必须在 module.json5 声明两项配置(querySchemes + wxentity.action.open,缺一不可,见 2.2)。
原理:HBuilderX 生成的鸿蒙 EntryAbility 继承运行时 UniEntryAbility,其 onCreate / onNewWant 内部会向 appAbilityEmitter 发出 create / newWant 事件,而 UTSHarmony.onAppAbilityCreate / onAppAbilityNewWant 订阅的正是这两个事件,因此插件必然能收到回跳 Want。注意鸿蒙平台只有「发行 → App-Harmony-本地打包」,不存在云打包。
已验证环境:uni-app(vue3)+ 自定义原生壳工程(DevEco Studio)+
@tencent/wechat_open_sdk@1.0.23+ HarmonyOS NEXT 真机(API 12 / API 13)+ 微信客户端 8.0.x;cli 侧@dcloudio/*锁定版本为3.0.0-5020620260917001。2026-11-18 已在独立 uni-app cli 工程真机跑通全链路:调起确认收款页 → 用户在微信侧取消回跳 → 宿主原生零改动、插件
UTSHarmony钩子接管成功 →onMerchantTransferResult与getLastMerchantTransferResult()均返回{"result":"cancel"}。
一、功能与平台
| 能力 | 说明 |
|---|---|
requestMerchantTransfer(options) |
调起微信确认收款页面(businessType=requestMerchantTransfer) |
onMerchantTransferResult(cb) |
【鸿蒙增强】一次性回调用户确认结果(success/fail/cancel) |
getLastMerchantTransferResult() |
【鸿蒙增强】轮询式读取最近一次确认结果 |
clearMerchantTransferResult() |
清除结果缓存 |
offMerchantTransferResult() |
注销未触发的结果回调 |
handleWeChatWant(want, appId?) |
【可选】自维护原生工程时手工转发 Want(常规接入由插件自动完成) |
setMerchantTransferAppId(appId) |
【冷启动兜底】预配 appId,使 onCreate 回跳的 Want 也能正常分发 |
| 平台 | 支持 |
|---|---|
| HarmonyOS NEXT(app-harmony) | ✅ |
| Android / iOS / H5 / 小程序 | ❌(请继续使用官方 uni-requestMerchantTransfer 或 wx.requestMerchantTransfer) |
范围界定:本插件只覆盖提现流程中「用户在微信里确认收款」这一步。发起转账仍需后端先调微信支付商家转账(转账到零钱)下单接口拿到 package_info;用户回传的 cancel 仅代表他未确认,不等于单据失败,到账与否请以自己的单据查询结果为准。
环境要求:
- uni-app 编译工具链 / HBuilderX ≥ 4.31:插件依赖
UTSHarmony.onAppAbilityCreate/onAppAbilityNewWant,其版本门槛来自@dcloudio/uni-app-runtime包内src/main/ets/uni-mp-sdk/types/UTSHarmony.d.ts的@uniPlatform标注harmony: { uniUtsPlugin: "4.31", uniVer: "4.31" }(即 uni-app 而非仅 uni-app x 的鸿蒙 UTS 插件自 4.31 起支持)。低于此版本钩子装不上,表现为「调起正常、确认结果永远取不到」。 - HarmonyOS NEXT API 12(5.0.0(12))及以上:
@tencent/wechat_open_sdk@1.0.23与@dcloudio/uni-app-runtime包内均声明compatibleSdkVersion: 12,低于 API 12 依赖装不上。API 版本属于宿主工程build-profile.json5的配置(插件包本身不携带),已在 API 12(5.0.0(12))与 API 13(5.0.1(13))真机验证;宿主工程的targetSdkVersion不影响插件可用性。 - uni-app vue3 工程
- 微信客户端 ≥ 8.0.11.34(低于此版本无法拉起确认收款页面)
- 微信开放平台已为宿主 App 配置鸿蒙平台(Bundle ID + appIdentifier),AppID 与调起参数
appId一致
二、集成步骤
2.1 安装插件
将 xyyt-wxmerchanttransfer 目录复制到工程 src/uni_modules/ 下(从插件市场导入同理)。插件依赖声明在 utssdk/app-harmony/config.json(@tencent/wechat_open_sdk@1.0.23)。
依赖落地方式分三种,请注意区分:
- HBuilderX 工程(运行到鸿蒙 / 本地打包):工具链会把 UTS 插件编成独立模块,并自动写入
build-profile.json5的 modules、oh-package.json5依赖与插件注册代码,无需手工处理。 - uni-app cli 工程(
uni build -p app-harmony):上述自动生成同样由工具链完成,宿主原生零改动即可加载插件(本插件 1.0.0 的全链路真机验证正是在独立 cli demo 工程完成的)。但要注意:cli 生成的dist/dev/app-harmony/dist/build/app-harmony是构建产物,其中entry/src/main/module.json5的两项宿主配置(见 2.2)没有官方覆盖入口 ——harmony-configs/是 HBuilderX 独有机制,在@dcloudio/*全包检索该字符串零命中。请把生成的鸿蒙工程纳入你自己的版本管理,或直接走下面第三种自维护权威工程路线。 - 已有自己的鸿蒙原生权威工程(离线打包 / 手工维护工程):
uni build -p app-harmony只产出dist/build/app-harmony,不会替你修改工程配置。需自行完成四步:ohpm install @tencent/wechat_open_sdk@1.0.23;- 根
build-profile.json5的modules注册插件模块(name须与模块自身src/main/module.json5的name完全一致,否则编译失败); entry/oh-package.json5加入本地模块依赖(形如"@uni_modules/xyyt-wxmerchanttransfer": "file:../xyyt_wxmerchanttransfer");- 在参与 ArkTS 编译的
entry/src/main/ets/uni_modules/index.generated.ets补import与uni.registerUTSPlugin(www下的同名文件只是资源,不参与编译)。缺这一步时运行时uni.requireUTSPlugin返回 undefined。
2.2 宿主 module.json5 配置(必须两项,缺一不可)
微信的「拉起」和「回跳」是两条独立通道,各自需要一个声明。只配一项时故障现象完全不同,且第二项缺失不会有任何报错提示:
| 配置项 | 位置 | 作用 | 缺失时的表现 |
|---|---|---|---|
querySchemes: ["weixin"] |
module 节点 |
允许 bundleManager.canOpenLink("weixin://") 查询 |
@tencent/wechat_open_sdk 的 isWXAppInstalled() 抛 BusinessError 17700056 并被内部吞成 false(设备其实装了微信)。插件会自己再调一次 canOpenLink 分流成因,此时 fail 回的是「宿主 querySchemes 未配置」并直接给出修改位置,不会误导用户去装微信 |
actions 含 wxentity.action.open |
module.abilities[].skills |
让微信确认收款后的回跳 Want 能路由回宿主 Ability |
拉起完全正常(确认收款页照样打开),但结果取不到:onMerchantTransferResult 不触发、getLastMerchantTransferResult() 恒为 null |
在 entry/src/main/module.json5 中按下面的层级配置(注意 actions 不在 module 下,必须嵌在 abilities[].skills[] 内):
{
"module": {
// ...
"querySchemes": ["weixin"],
"abilities": [
{
"name": "EntryAbility",
// ...
"skills": [
{
"entities": ["entity.system.home"],
"actions": ["action.system.home", "wxentity.action.open"]
}
]
}
]
}
}
早期版本文档把
actions与querySchemes平级写在module节点下,是错的 —— 照抄不会生成预期的 intent 过滤,回跳同样收不到。若你已按旧片段配置过,请重新核对层级。
三类工程的落地方式
manifest.json 里没有任何开关能生成这两项,只能落到原生 module.json5;区别在于改哪一份、改完会不会被后续构建冲掉:
- HBuilderX 工程(发行 → App-Harmony-本地打包):
module.json5属于打包生成的中间产物,直接改容易被重新生成覆盖。建议通过项目根目录harmony-configs/提供完整的module.json5覆盖(该目录内文件是原样整体覆盖,不能只给片段);注意manifest.json中的鸿蒙配置优先级高于harmony-configs。 - uni-app cli 工程:
entry/src/main/module.json5存在于构建产物dist/dev|build/app-harmony里,改它照样生效(本插件真机验证即如此),但它是生成物 —— 删dist重建或换机器构建都会丢,而harmony-configs/对 cli 并不起作用。因此要么把生成的鸿蒙工程纳入你自己的版本管理并在重建后核对这两项是否还在,要么转为下面一种形态。 - 自维护原生权威工程:
entry/src/main/module.json5是长期存在的源文件,直接编辑即可。但如果你的构建脚本会用模板重新生成整个entry目录,请把这两项写进模板、或在脚本里加一步 patch,否则改动会被下一次构建冲掉。
改完必须重新构建并安装 HAP 才生效:module.json5 编译进 HAP,WGT 热更新、替换 www 目录都不起作用。落地后建议做产物级确认 —— 解包 HAP 检查其中的 module.json 是否真的带上了 querySchemes 与 wxentity.action.open,不要只看源文件。
插件自带的
utssdk/app-harmony/module.json5定制机制代劳不了这两项:uni-uts-v1(dist/arkts/index.js,源码注释即「以下文件用户可定制」)会读取插件的该文件、与默认值合并后写入插件模块自身的src/main/module.json5。而querySchemes必须在发起canOpenLink的 entry 模块声明、skills.actions挂在 entry 的EntryAbility上,两者都不在插件模块内 —— 所以这两项只能由宿主自己配。
2.3 微信回跳 Want 的接收(插件自动完成,无需改原生)
插件加载时通过 UTSHarmony.onAppAbilityCreate / UTSHarmony.onAppAbilityNewWant 监听宿主 EntryAbility 生命周期,自行接管微信回跳的 Want 并交给微信 SDK 分发。前者覆盖冷启动回跳,后者覆盖应用存活时的回跳。
因此 HBuilderX 工程(鸿蒙只有本地打包,不存在云打包)不需要修改任何原生代码,完成 2.1、2.2 后即可直接使用。若确实要改动生成的原生文件,可通过项目根目录下的 harmony-configs 目录覆盖:该目录内文件是原样整体覆盖(因此必须提供完整文件而非片段),且 manifest.json 中的鸿蒙配置优先级高于 harmony-configs。
前提:插件必须被前端静态引用才会进入编译范围(见第四节注意事项 7),否则钩子不会安装。
冷启动回跳(App 已被系统回收)
用户长时间停留在微信确认收款页面、宿主进程被回收时,回跳走 onCreate,此时插件还未调起过、内部没有 WXApi 实例,无法确定 appId。两种处理方式:
- 在
App.vue的onLaunch里调一次setMerchantTransferAppId('wxYourAppId')(推荐,一行代码,无原生改动); - 或忽略:插件会把该 Want 暂存,待下一次
requestMerchantTransfer或setMerchantTransferAppId时自动补投。
<script setup>
// #ifdef APP-HARMONY
import { setMerchantTransferAppId } from '@/uni_modules/xyyt-wxmerchanttransfer'
setMerchantTransferAppId('wxYourAppId')
// #endif
</script>
2.4 可选:自维护原生工程手工转发 Want
仅在以下场景需要:你自己的鸿蒙工程直接持有 EntryAbility(离线打包 / 原生权威工程),且希望在原生层显式控制分发时机。常规接入无需本节。
import { handleWeChatWant } from '@uni_modules/xyyt-wxmerchanttransfer'
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
handleWeChatWant(want);
// ...原有逻辑
}
onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
handleWeChatWant(want);
// ...原有逻辑
}
完整示例见插件内 native-integration/EntryAbility.example.ets。
不要与自动接管叠加:若宿主已手工转发,插件内部钩子会再转发一次,同一 Want 被
handleWant两次。微信 SDK 对非本插件类型的 resp 会忽略,但为避免歧义,两种方式二选一即可。
2.5 页面调用
<script setup lang="ts">
// #ifdef APP-HARMONY
import {
requestMerchantTransfer,
onMerchantTransferResult,
getLastMerchantTransferResult
} from '@/uni_modules/xyyt-wxmerchanttransfer'
// #endif
// 1) 先注册结果回调(一次性,触发后自动注销)
// #ifdef APP-HARMONY
onMerchantTransferResult((res) => {
// res.result: 'success' | 'fail' | 'cancel'
// res.errMsg: 微信回传的 extMsg 原始 JSON,如 {"result":"success"}
if (res.result === 'success') {
uni.showToast({ title: '请留意到账结果', icon: 'none' })
}
})
// #endif
// 2) 调起确认收款(package 为后端"转账单据"应答中的 package_info,
// 仅当单据状态为 WAIT_USER_CONFIRM 时返回)
function receive() {
// #ifdef APP-HARMONY
requestMerchantTransfer({
mchId: '1900000109', // 示例商户号(微信官方文档样例),换成你的商户号
appId: 'wxYourAppId', // 换成你的微信开放平台 AppID
package: 'xxxxxxxx', // 后端转账单据应答中的 package_info
success: (res) => {
// 仅代表页面拉起成功
console.log('拉起成功', res.errMsg)
},
fail: (res) => {
uni.showToast({ title: res.errMsg, icon: 'none' })
}
})
// #endif
}
// #endif
</script>
不想用回调也可以轮询读取:
// #ifdef APP-HARMONY
const timer = setInterval(() => {
const r = getLastMerchantTransferResult()
if (r != null) {
clearInterval(timer)
// 处理 r.result ...
}
}, 1000)
// #endif
三、API
requestMerchantTransfer(options)
调起微信确认收款页面。字段与官方 uni.requestMerchantTransfer 一致:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| mchId | string | 是 | 微信支付商户号 |
| appId | string | 是 | 微信开放平台移动应用 AppID |
| package | string | 是 | 转账单据应答的 package_info(状态 WAIT_USER_CONFIRM 时返回) |
| openId | string | 否 | 用户在微信开放平台 appid 下的唯一标识 |
| subAppId | string | 否 | 服务商模式:子商户 appid |
| subMchId | string | 否 | 服务商模式:子商户号 |
| success | callback | 否 | 调起成功(页面拉起意图已发出) |
| fail | callback | 否 | 调起失败(参数缺失 / querySchemes 未配置 / 未安装微信或版本过低 / 发送失败) |
| complete | callback | 否 | 结束回调 |
回调结果:{ errMsg: string },success 时为 requestMerchantTransfer:ok。
onMerchantTransferResult(callback)【鸿蒙增强】
注册一次性用户确认结果回调;微信回跳后触发并自动注销。
| 字段 | 说明 |
|---|---|
| res.result | success(微信确认收款页面展示成功,不代表确认成功,到账以订单/列表接口为准)| fail | cancel |
| res.errMsg | 微信回传 extMsg 原始 JSON 字符串,如 {"result":"success"} |
getLastMerchantTransferResult() / clearMerchantTransferResult()
轮询式读取/清除最近一次结果,用法见上文。
handleWeChatWant(want, appId?)【宿主集成】
把微信回跳的 Want 交给插件分发;返回 false 表示插件未处理(如尚未建立 WXApi)。与宿主其他微信能力共存,见 2.3。
四、注意事项
- result 语义:微信官方定义回调
success仅表示"确认收款页面展示成功",不代表用户已确认或资金到账;业务侧请以刷新后的订单/列表接口为准。 - UTS 产物属原生层,插件自身升级需重打包:插件代码被编译为 ArkTS 打进 HAP,不在 JS 层,因此插件版本升级无法靠 WGT 热更新覆盖;但接入本身已不需要宿主改原生代码,不再为此维护原生工程。
- 重复调起:
onMerchantTransferResult为一次性回调;同一时刻仅保留最后一次注册。重复调起前建议先处理上一次结果(或改用轮询 API)。 - 依赖冲突:若宿主同时集成微信登录插件(uni-oauth-weixin),其传递依赖同为
@tencent/wechat_open_sdk,ohpm 自动去重,无需处理;若出现版本不一致,可在鸿蒙工程根oh-package.json5的overrides中统一版本。 - 服务商模式:传
subAppId/subMchId时 query 由微信侧校验,mchId传服务商商户号。 - uni-app x:本插件仅在 uni-app(vue3)鸿蒙端验证,因此
package.json中 uni-app x 鸿蒙声明为不支持(-)。uvue / uni-app x 工程请勿直接引用;如确有需求,请先自行验证编译与运行,后续版本可据验证结果再开放。 - HBuilderX 工程须保留一条页面静态 import:UTS 插件只有在被前端静态引用时才会纳入编译范围。若只在原生
EntryAbility引用handleWeChatWant、页面侧无任何 import,HBuilderX 不会编译utssdk/app-harmony/index.uts,运行时uni.requireUTSPlugin返回 undefined。请在任一#ifdef APP-HARMONY页面保留import ... from '@/uni_modules/xyyt-wxmerchanttransfer'(demo 页即示例)。改动插件引用关系后,需先删除工程dist/(HBuilderX 工程为unpackage/)再重新运行,否则会复用旧的“未被引用”判定。对普通插件这只是编译问题,对本插件则是功能前提:生命周期钩子在插件模块加载时才安装,插件没进编译范围就等于钩子不存在,调起依然能发起、但确认结果永远回不来。
五、Demo
配套 demo 工程(uni-app cli,vue3)以 src/pages/index/index.vue 演示完整流程(参数输入 → 调起 → 结果回调与轮询展示),插件源码位于 src/uni_modules/xyyt-wxmerchanttransfer/。真机验证只需按 2.1、2.2 完成(插件自动接管 Want,无需改原生);2.2 的两项配置少一项就会出现「拉得起但取不到结果」或「报未能拉起微信(并提示 querySchemes 未配置)」,建议按该节末尾的产物级方式先确认再上机。
六、已知限制
- 仅鸿蒙端生效;Android/iOS 请用官方插件(本插件不重复实现)。
- 结果回传依赖微信回跳
Want被成功分发,且依赖module.json5的wxentity.action.open(见 2.2):缺该 action 时拉起不受任何影响,但回跳 Want 路由不回宿主,结果恒为空。 - 常规场景由插件内部 UTSHarmony 钩子自动接管;若插件未被前端静态引用(注意事项 7)或宿主 uni-app 编译工具链低于 4.31,钩子装不上,此时调起可发起但收不到确认结果,需升级工具链或按 2.4 手工转发。
- 已获真机结论的机制:
onAppAbilityNewWant(应用存活时回跳)+ 一次性回调 + 轮询读取,2026-11-18 独立插件工程真机返回{"result":"cancel"}。 - 尚无真机结论的机制:
onAppAbilityCreate冷启动回跳与「暂存 Want 后续自动补投」,目前仅有工程与编译层证据。若你的场景回跳异常,先用getLastMerchantTransferResult()轮询定位,并核对 2.2 的两项配置。

收藏人数:
下载插件并导入HBuilderX
下载示例项目ZIP
赞赏(0)
下载 54
赞赏 0
下载 12773692
赞赏 1960
赞赏
京公网安备:11010802035340号