openx-wps-jssdk 使用说明

概述

openx-wps-jssdk 是一个专为 CNKI 研学业务 与 WPS 平台集成场景 开发的 JavaScript SDK。
该 SDK 在原生 WPS SDK 基础上进行了深度封装，简化了研学业务中 授权、订单、支付、溯源 等复杂流程。

版本历史

v0.0.3（2025/11/05）

• 处理 WPS accessToken 在研学场景下 Cookie 种植互不相认问题。

快速开始

安装与引入

npm install openx-wps-jssdk --save

或者直接在页面中引入构建后的包：

<script src="https://piccachex.cnki.net/dynamic/js/openx-wps-jssdk-0.0.1.js"></script>

加载完成后，全局会注册 window.openx 对象。

初始化

在页面加载完成后进行初始化配置：

openx.config({
  appid: 'XXX',       // 研学应用 appId
  wpsAppid: 'XXX',    // WPS 应用 id，每个应用独立
  env: ''             // 环境标识：test / production
})

等待 SDK Ready

成功配置后，需调用 openx.ready() 方法，等待 WPS SDK 完全加载（触发 WpsofficeSDKReady 事件）后再执行业务逻辑。

示例（Vue 项目中使用）

;(async () => {
  openx.config({
    appid: 'xxx',
    wpsAppid: 'xxx',
    env: process.env.VUE_APP_FLAG === 'xtest' ? 'test' : 'production'
  })

  // 开发环境可以不选择 ready
  if (process.env.NODE_ENV === 'production') {
    await openx.ready()
  }

  new Vue({
    router,
    store,
    render: h => h(App)
  }).$mount('#app')
})()

安全认证

WPS 退出登录监听

SDK 已集成退出登录监听，当 WPS 用户登出后，会自动关闭当前业务页。

获取 WPS 认证信息

SDK 自动封装了 Token 获取与缓存逻辑：

const wpsAccRes = await openx.getAccessToken()
console.log(wpsAccRes.content.accessToken)

• 优先从 Cookie 中读取 accessToken、openId；
• 若无缓存或已过期，会自动触发 WPS 登录授权流程；
• 若存在 refreshToken，则自动刷新；
• 返回当前用户客户端 WPS 版本号信息。

返回结构

{
  "code": 0,
  "message": "获取成功",
  "content": {
    "accessToken": "xxx",
    "openId": "xxx",
    "version": "xxx"
  }
}

支付与下单

发起预下单并唤起支付

try {
  const res = await openx.purchase({
    product: 'xxx', // 商品 ID / 权益码
    type: 'prepay', // 订单类型：buyMerchandiseByBillno 或 prepay
    title: 'AI 文献综述月卡',       // 仅 prepay 可选
    desc: '支持 AI 智能选题与文献管理', // 仅 prepay 可选
    complete: (res) => {
      if (res.status) {
        // 购买成功
      }
    }
  })
  console.log('发起支付成功：', res)
} catch (error) {
  console.error('下单失败：', error)
}

SDK 会自动完成以下流程：

1. 校验/刷新 JWT 授权；
2. 获取研学用户信息（getUserInfo）；
3. 调用创建订单接口（createOrder）；
4. 调用 WPS 原生 prepay / buyMerchandiseByBillno 完成支付；
5. 监听支付结果并返回统一结构。

双通道混用原则

在整个购买流程中：

• Promise 用于返回一次性的最终结果；
• 回调（complete） 用于实时推送 WPS SDK 的过程状态（如取消支付、支付成功等）。

二者互不冲突、互相补充。

统一返回结构

所有核心方法（如 purchase、getRefreshToken 等）都遵循统一的返回结构：

| 字段 | 类型 | 说明 | | --------- | ------ | ---------------- | | code | number | 状态码 | | message | string | 结果说明 | | content | object | 业务数据（如订单号、支付凭证等） |

状态码说明

| code | 含义 | 说明 | | ---- | ---- | ------------------------------ | | 0 | 成功 | 请求成功 | | -1 | 失败 | 网络异常、参数错误或接口异常 | | 9001 | 登录失效 | LID 或 WPS accessToken 过期，需重新登录 |

特别说明

1. SDK 内置独立的 JWT 授权体系，保障订单与支付接口在 WPS 容器环境中的安全调用，支持后期链级别溯源追踪。
2. 若接口返回 code = 9001，表示当前登录状态失效（如 LID 或 WPS accessToken 过期），业务层需立刻重定向至统一登录页面，重新执行授权流程，以恢复有效会话。