更新记录

1.0.0（2026-02-03）

• 新增：startPay 发起银联支付（App-Android / App-iOS / App-Harmony）
• 新增：handlePaymentResult 回调处理/兜底（主要用于 iOS / Harmony）
• 新增：setLogEnabled / isLogEnabled 控制插件日志输出
• 完善：package.json 平台支持矩阵与关键词信息

平台兼容性

uni-app(4.87)

uni-app x(4.87)

hans-unionpay

银联「线上收银台（通用版）」支付控件 UTS 插件（仅 App 端）。

购买建议：请先在测试环境使用测试参数（例如 mode='01'）完成联调与回调验证，确认满足需求后再购买。

支持平台：

• App-Android
• App-iOS
• App-Harmony

不支持 web/mp/快应用/云端等平台；编译到不支持的平台会因缺少实现而失败。

安装

• 将插件放入项目 uni_modules/hans-unionpay（或通过插件市场安装）。

平台配置

Android

• 通常无需额外配置；插件已包含必要的声明与适配。

iOS

在宿主 Info.plist 配置：

• URL Types：添加你传入 startPay({ scheme }) 的回跳 scheme（例如 hansunionpay）
• LSApplicationQueriesSchemes：建议加入 uppaysdk（避免 canOpenURL 受限影响唤起能力）

Harmony

在宿主 module.json5 注册回跳 URI（建议 launchType=singleton，避免回跳时重启导致回调丢失）：

{
  "skills": [
    {
      "entities": ["entity.system.browsable"],
      "actions": ["ohos.want.action.viewData"],
      "uris": [{ "scheme": "hansunionpay", "host": "uppayresult" }]
    }
  ]
}

用法

发起支付

import { startPay } from '@/uni_modules/hans-unionpay'

startPay({
  tn: 'your-tn',
  mode: '01', // '00' 生产 / '01' 测试
  scheme: 'hansunionpay',
  success: (res) => console.log('unionpay success', res),
  fail: (err) => console.error('unionpay fail', err),
  complete: (res) => console.log('unionpay complete', res)
})

处理回调（兜底）

handlePaymentResult 主要用于 iOS / Harmony 的回跳处理（Android 不使用该方法）。

iOS（uni-app x）

uni-app x 下插件会通过 UTSiOSHookProxy 自动接收 openURL 并解析结果；一般无需业务额外接线。

如遇到工程结构导致未触发（或你拿到了回跳 URL），可手动兜底调用：

import { handlePaymentResult } from '@/uni_modules/hans-unionpay'

handlePaymentResult({
  url: 'hansunionpay://uppayresult?code=...',
  complete: (res) => console.log('unionpay callback', res)
})

iOS（uni-app / App.vue）

uni-app（非 x）场景下，iOS 的 openURL 回跳通常需要业务在 App.vue 主动监听并转发给插件处理。

下面是一个“尽量兼容”的最小接线（监听 openURL + 读取 plus.runtime.arguments，并做去重与延迟重试）：

// App.vue
<script>
import { handlePaymentResult } from '@/uni_modules/hans-unionpay'

let lastUrl = ''

function forwardUrl(url) {
  const u = `${url || ''}`.trim()
  if (!u || u.indexOf('://') < 0) return
  if (u === lastUrl) return
  lastUrl = u
  handlePaymentResult({
    url: u,
    complete: (res) => console.log('[unionpay] handlePaymentResult.complete', res)
  })
}

function readRuntimeArguments(source) {
  try {
    const args = `${plus?.runtime?.arguments || ''}`.trim()
    if (args.indexOf('://') >= 0) forwardUrl(args)
  } catch (_e) {}
}

function installOpenUrlListener() {
  try {
    if (!plus?.runtime?.addEventListener) return
    const handler = (e) => forwardUrl(e?.url)
    plus.runtime.addEventListener('openURL', handler, false)
    // 兼容不同大小写/历史事件名（不同运行时可能有差异）
    plus.runtime.addEventListener('openUrl', handler, false)
    plus.runtime.addEventListener('openurl', handler, false)
  } catch (_e) {}
}

function pollArguments(source) {
  ;[0, 60, 160, 320, 650, 1100, 1600].forEach((ms) => {
    setTimeout(() => readRuntimeArguments(`${source}:${ms}`), ms)
  })
}

function retryInstall(source) {
  ;[0, 60, 160, 320].forEach((ms) => {
    setTimeout(() => {
      try {
        installOpenUrlListener()
        readRuntimeArguments(`${source}:retry:${ms}`)
      } catch (_e) {}
    }, ms)
  })
}

export default {
  onLaunch() {
    // #ifdef APP-PLUS
    installOpenUrlListener()
    readRuntimeArguments('onLaunch')
    pollArguments('onLaunch')
    retryInstall('onLaunch')
    // #endif
  },
  onShow() {
    // #ifdef APP-PLUS
    installOpenUrlListener()
    readRuntimeArguments('onShow')
    pollArguments('onShow')
    retryInstall('onShow')
    // #endif
  }
}
</script>

iOS 侧还需要确保 Info.plist 的 URL Types 已配置 scheme，并且与你调用 startPay({ scheme }) 传入的一致；修改 Info.plist 后通常需要重新制作/安装自定义基座才会生效。

Harmony

Harmony 回跳 URI 通常形如：<scheme>://uppayresult?...。插件已尝试通过 UTSHarmony.onAppAbilityCreate/onAppAbilityNewWant 自动处理 want.uri。

如你能拿到回跳 URI，也可以手动兜底调用：

import { handlePaymentResult } from '@/uni_modules/hans-unionpay'

handlePaymentResult({
  url: 'hansunionpay://uppayresult?code=success&data=...',
  complete: (res) => console.log('unionpay callback', res)
})

API

• startPay({ tn, mode, scheme?, seType?, success, fail, complete })
• handlePaymentResult({ url, complete })
• setLogEnabled(enabled)（控制插件自身及原生层 console 日志；默认开启）
• isLogEnabled()