lingxi-wechat-entrust

v4.2.2

Published

4 days ago

`lingxi-wechat-entrust` 在微信小程序中通过 `web-view` 嵌入灵析筹款项目，衔接网页与小程序原生支付能力：

0High
0Medium
0Low

symo

灵析微信小程序支付与代扣签约组件

lingxi-wechat-entrust 在微信小程序中通过 web-view 嵌入灵析筹款项目，衔接网页与小程序原生支付能力：

定期捐：接收网页提供的签约参数，跳转微信签约小程序，返回后打开签约结果页。
单次捐：接收网页提供的支付参数，调用 wx.requestPayment，成功后打开支付结果页。
中转页：通过页面往返和销毁、重建 web-view，接收网页消息并触发后续流程。

安装与接入

1. 安装 npm 包

在业务小程序的 npm 项目目录执行：

npm install --save lingxi-wechat-entrust

在微信开发者工具中执行“工具 → 构建 npm”。实际使用版本以业务项目安装结果为准。

2. 注册页面

在业务小程序 app.json 的 pages 中加入以下页面；已有页面配置应保留：

{
  "pages": [
    "pages/index/index",
    "pages/cf/index",
    "pages/cf/placeholder"
  ]
}

3. 创建筹款页

pages/cf/index.json：

{
  "usingComponents": {
    "lingxi-cf-view": "lingxi-wechat-entrust/cf/cf"
  }
}

pages/cf/index.js：

Page({
  data: {
    projectId: '替换为实际筹款项目ID',
    queryString: '?embed=1',
    baseUrl: 'https://cf.lingxi360.com/p/',
    shouldReattachWebview: false
  }
})

pages/cf/index.wxml：

<lingxi-cf-view
  project-id="{{projectId}}"
  query-string="{{queryString}}"
  base-url="{{baseUrl}}"
  should-reattach-webview="{{shouldReattachWebview}}"
></lingxi-cf-view>

定期捐和单次捐使用同一组件，具体流程由网页消息决定。请替换项目 ID，并与网页侧确认查询参数。

4. 创建中转页

pages/cf/placeholder.json：

{
  "usingComponents": {
    "lingxi-placeholder-view": "lingxi-wechat-entrust/placeholder/placeholder"
  }
}

pages/cf/placeholder.js：

Page({})

pages/cf/placeholder.wxml：

<lingxi-placeholder-view></lingxi-placeholder-view>

中转组件会将上一页的 shouldReattachWebview 设为 true，然后调用 wx.navigateBack()。筹款页必须声明同名数据并绑定给筹款组件。不要将中转页设为首页或单独打开。

5. 从落地页点击进入

pages/index/index.wxml 可使用：

<navigator url="/pages/cf/index">进入筹款项目</navigator>

组件参数

| WXML 属性 | 类型 | 源码默认值 | 说明 | | --- | --- | --- | --- | | project-id | String | 内置演示项目 ID | 接入时显式传入实际筹款项目 ID。 | | query-string | String | 内置演示渠道参数，以 ?utm_bccid= 开头 | 包含前导 ? 的完整查询串；无参数时显式传入空字符串。 | | base-url | String | https://cf.lingxi360.com/p/ | 项目链接前缀，需要保留末尾 /。 | | should-reattach-webview | Boolean | false | 必须绑定页面同名数据，用于中转后重建 web-view。 |

项目地址直接按 baseUrl + projectId + queryString 拼接，不会自动添加分隔符或编码。

例如查询串可为 ?utm_bccid=实际渠道ID&embed=1。若业务流程需要 openid，应先由业务小程序取得，再按网页接口约定传入；当前演示项目的单次捐页面采用此方式。动态参数值需要自行 URL 编码。

当前仅监听 queryString 变化来刷新项目地址；组件挂载后若单独修改 projectId 或 baseUrl，不会自动刷新。建议在展示组件前准备好参数。

网页消息协议与流程

组件通过 web-view 的 bindmessage 接收 e.detail.data 数组，依次处理其中的 { action, params }。网页可使用微信 JS-SDK 的 wx.miniProgram.postMessage({ data: { action, params } }) 发送消息。

| action | params | 用途 | | --- | --- | --- | | setEntrustParams | 签约参数对象 | 保存签约参数，将项目类型设为定期捐。 | | setBindReturnUrl | URL 字符串 | 保存签约成功后的网页地址。 | | setPaymentParams | 支付参数对象 | 保存支付参数，将项目类型设为单次捐。 | | setPaymentSuccessUrl | URL 字符串 | 保存支付成功后的网页地址。 |

每次发起流程前，网页应发送对应类型的参数和结果页地址，再通过小程序页面跳转进入约定的中转页。组件依赖页面往返和 web-view 销毁来接收消息，不能将 postMessage 当作实时调用支付的接口。

定期捐签约

setEntrustParams.params 的字段按当前 navToContractPage 实际读取的名称传入：

appid, contract_code, contract_display_account, mch_id, outerid,
notify_url, plan_id, request_serial, timestamp, sign

字段大小写以此为准，尤其是 appid、request_serial。参数应来自服务端，不应在客户端生成签名。

网页发送 setEntrustParams 和 setBindReturnUrl，进入中转页。
中转页返回筹款页，组件重建 web-view 后调用 wx.navigateToMiniProgram。
签约目标在源码中固定为 wxbd687630cd02ce1d，路径为 pages/index/index。
返回时，组件监听场景值 1038，核对来源 AppID；仅当 extraData.return_code === 'SUCCESS' 时，将网页切换到已保存的签约结果页。

extraData 缺失或签约失败时，当前实现只记录日志，不会查询服务端或展示专门的失败页。最终签约结果应由业务服务端确认。

单次捐支付

setPaymentParams.params 需要提供以下字段：

timeStamp, nonceStr, package, signType, paySign

其中 timeStamp 大小写必须一致。当前源码将 signType 原样传给 wx.requestPayment，不再固定为 MD5，应与服务端生成的支付参数一致。

网页发送 setPaymentParams 和 setPaymentSuccessUrl，进入中转页。
中转页返回后，组件调用 wx.requestPayment。
支付接口回调成功时打开已保存的支付结果页；取消或失败时重新打开原始项目地址。

当前组件没有通过 triggerEvent 向业务页面发送支付或签约结果事件。客户端回调和结果页跳转不能替代服务端对最终业务状态的确认。

本地开发

npm install
npm run dev

npm run dev 将组件生成到 miniprogram_dev/components/，并写入演示项目的 package.json、安装其依赖。
npm run watch 持续构建；同时监听 tools/demo/ 并将变动同步到演示目录。
npm run build 或 npm run dist 生成 npm 使用的 miniprogram_dist/。

miniprogram_dev/ 是独立 Git 子模块。首次检出时如需取得演示项目，可执行 git submodule update --init --recursive，需要具有子模块仓库的访问权限。

在微信开发者工具中打开仓库根目录（miniprogramRoot 已指向 miniprogram_dev/），或直接打开 miniprogram_dev/，配置自己的 AppID 和业务环境并构建 npm。两处配置均为普通小程序类型（compileType: "miniprogram"），无需配置 pluginRoot。演示项目使用云开发获取 openid，需配置相应云环境及云函数；组件本身不依赖该获取方式。

演示项目的定期捐、单次捐和中转页直接引用本地构建路径 ../../components/cf/cf 和 ../../components/placeholder/placeholder，用于调试当前源码。首次运行前需执行 npm run dev 或 npm run watch 生成这些文件；npm run build 仅生成发布目录，不会更新演示目录。Babel 辅助函数随组件打包，无需由小程序在运行时解析 @babel/runtime/helpers/*。若要验证发布的组件包，应在演示项目中安装目标版本，将组件引用切换为本文接入示例中的 npm 路径，再重新构建 npm。

现有定期捐演示页还将 query-string 绑定到未声明的 queryString1；接入请使用上面的完整示例。

常用命令

| 命令 | 作用 | | --- | --- | | npm run dev | 一次开发构建并准备演示依赖。 | | npm run watch | 监听源码和演示模板变动。 | | npm run build / npm run dist | 构建发布目录。 | | npm test | 运行 Jest 测试，需先构建。 | | npm run test-debug | 调试 Jest 测试。 | | npm run coverage | 生成测试覆盖率报告。 | | npm run lint / npm run lint-tools | 检查并自动修改源码或构建脚本格式。 | | npm run clean | 删除 miniprogram_dist/。 | | npm run clean-dev | 删除开发产物及整个 miniprogram_dev/ 目录。 |

miniprogram_dev/ 包含独立演示源码，执行 clean-dev 前应保存其修改。当前测试仍包含模板渲染和模拟微信 API 用例，未覆盖真实支付、签约和页面往返流程；这些流程需要目标小程序真机验收。

test/bundle.test.js 用于检查开发和发布组件在没有外部 npm 模块解析能力时能否加载，并验证网页消息处理。先生成两处产物，再运行：

npm run dev
npm run build
npm test -- test/bundle.test.js --runInBand --transform '{}'

此处关闭 Jest 的源码转换，直接验证构建产物；现有 Jest 23 默认转换器使用 Babel 6，与当前 Babel 7 配置不兼容。

构建与发布

发布前先构建并核对打包内容：

npm run build
npm pack --dry-run

确认 miniprogram_dist/cf/cf.*、miniprogram_dist/placeholder/placeholder.* 等组件文件存在且包含目标改动，再按项目发布流程执行 npm login、npm publish。package.json 的 miniprogram 字段指向 miniprogram_dist，不能仅修改源码就直接发布。

目录结构

src/
  cf/                 筹款 web-view、消息处理、支付与签约流程
  placeholder/        中转组件
  index.*             构建入口，通过 usingComponents 引入两个组件
  lib.ts              模板 API 示例
  utils.js            工具与实时日志封装
miniprogram_dev/       独立子模块：业务接入演示及本地开发产物
miniprogram_dist/      发布产物（构建生成）
test/                 Jest / miniprogram-simulate 用例
tools/                构建、资源检查及演示模板
gulpfile.js           Gulp 任务入口

构建配置位于 tools/config.js，入口为 index 和 lib。构建脚本递归扫描 usingComponents 收集组件文件，因此 cf/cf 与 placeholder/placeholder 会随入口构建。

许可证

MIT