多彩宝 JSSDK 文档

# 使用指南

全新版的多彩宝 JSSDK。

# 设计思路

  • 对齐小程序：尽量对齐微信小程序 API 的设计，减少开发者记忆负担，同时也为以后可能的小程序化铺些路。
  • 同类收敛：同类型的 API 尽量通过一个接口对外服务并统一返回值的数据类型，减少开发者心智负担。
  • 类型友好：采用 TypeScript 编写，编译为 JavaScript 发包，附带类型定义，让 IDE 可自动提示，免去手动翻找文档的麻烦。
  • 注释即文档：将文档写进注释，既可免去使用时手动翻找文档的麻烦，也可写个脚本自动生成标准化的文档网站。
  • 统一入口：类比小程序的 wx、tt 等，提供 dcb 作为所有 API 的入口。
  • 异步化：采用 Promise 封装，将全部 API 异步化，避免回调地狱等问题。

# 安装

# 使用 npm 或 yarn 或 pnpm 安装 推荐

这是推荐的安装方式，你可获得 IDE 对 dcb.* 系列 API 的智能提示。

# 多彩宝内网用户

对于多彩宝内部同事，请优先使用前端团队自建 npm 源安装。

前置要求

执行安装命令前务必在项目根目录的 .npmrc 文件（没有则新建）里指定 @dcb 域下的包去自建 npm 拉取：

@dcb:registry=https://npmjs.gogpay.cn

# npm
npm i @dcb/jssdk

# or, yarn
yarn add @dcb/jssdk

# or, pnpm
pnpm add @dcb/jssdk

# 外部开发者

我们将 JSSDK 同步发布到了官方 npm 源，因此对于外部开发者，可使用官方 npm 源安装。

# npm
npm i @dcbfe/jssdk

# or, yarn
yarn add @dcbfe/jssdk

# or, pnpm
pnpm add @dcbfe/jssdk

# 使用

import { dcb } from '@dcb/jssdk';

async function main() {
  const appInfo = await dcb.getAppInfo();
}

main();

# 参与贡献

参与贡献可以是新增 API、解决 bug、完善文档等，若你使用 git 方式参与贡献，在你参与的 API 下面会自动加上你的名字，你也可以联系本项目的维护者提出你的建议。下面是主要的贡献流程，请遵守：

# 克隆项目

git clone ssh://git@git.gogpay.cn:7999/dcbfron/dcb-jssdk.git

# 安装依赖

若你未安装 node.js，请先安装：https://nodejs.org/zh-cn/ (opens new window)。

# npm
npm i

# or, yarn
yarn

# or, pnpm
pnpm i

# 创建分支

不要直接在 master 分支贡献代码！ 比如你这次要新建个 openDocument 的 API，那就创建个 api/openDocument 的分支，然后在该分支贡献代码：

git checkout -b api/openDocument

# 开始开发

# 如何封装一个新的 API

  • 首先使用命令 npm run docs:dev 开始文档服务；
  • 接着使用 npm run api:new 创建新的 API；
  • 然后打开新 API 的文件编写代码，其间可以打开 docs/demo/demo.vue 编写新 API 的演示代码并用多彩宝 App 扫码测试是否正确；
  • 最后，若测试正常，使用命令 npm run docs:gen-api 重新生成 API 文档，并查看生成的文档是否正常。

# 发布流程

在你创建的分支上完成开发并提交，然后发起 Pull Request，由维护的同事 Review 合并，进行后续的发包等流程。

若主分支有更新，请这样同步代码：

# 检出 master
git checkout master

# rebase
git pull --rebase origin master

# 检出你的分支
git checkout 你的分支名

# rebase
git rebase master

注意：一个分支只做一件事（或一类事），分支合并后就不应该再继续在该分支进行开发，新的事项请新建分支开发。

# commit 规范

为了自动生成更新日志（实质上就是自动提取 git 提交记录生成更新日志），请遵循以下规范：

# 特性（feature）增加以 feat: 开头
git commit -m "feat: 新增 openDocument"
git commit -m "feat: openDocument 支持打开 docx"

# bug 修复以 fix: 开头
git commit -m "fix: 解决 openDocument 不能打开 ppt 的问题"

# 其他不必加入更新日志的记录以 chore: 开头
git commit -m "chore: 更新代码风格"

# 前端-客户端交互规范

# 客户端接口实现规范

# 接口命名规范

尽量用 动词+名词 的形式命名。比如：

  • 选择图片：chooseImage
  • 显示弹窗：showModal
  • 打开选择器：openPicker
  • 扫码：scanCode

# 接口入参规范

入参必须为对象，这样有利于接口的后续扩展升级，比如：

要实现一个选择图片（chooseImage）的接口，刚开始需求可能只有一个：可以传递最多选择的图片个数，然后我们就将入参设计为一个数字，表示图片个数。随着业务迭代，又新增一个需求：可以传递可以选择的图片类型，此时现有的接口就不满足需求了。如果把入参设计为一个对象，则新增需求就是新增一个属性的事情：

interface ChooseImageParams {
  // 图片个数
  count: number;

  // 图片类型
  type: 'jpg' | 'png' | 'gif';
}

# 接口结果规范

结果必须为指定数据类型的对象，这样前端方可识别接口执行成功、失败：

特别注意

接口不要参与 UI 过程，如何处理接口返回结果由具体业务决定。具体包括两方面：

  • 接口可以对入参校验，但校验失败请不要弹出任何 UI 提示（比如 toast），请直接按规范返回错误信息即可；
  • 接口执行成功、失败都不要弹出任何 UI 提示（比如 toast），请直接按规范返回相关信息即可。
interface ApiResult {
  // 状态码，200 成功，非 200 失败
  status: number;

  // 信息，状态码非 200 时必须提供
  msg: string;

  // 返回数据，必须为一个对象，理由同接口入参规范
  data: Object;
}

# 前端接口调用规范

此处所述内容已经在本 JSSDK 内部实现，非本 JSSDK 的开发人员可不必深入了解。

# 如何处理接口返回结果

因为一些历史原因，需要兼容不标准的接口返回结果：

  • 若返回结果不是对象，尝试对结果进行 json 解析，若解析成功，将解析结果作为返回结果从头开始处理；若解析失败，视为成功，将返回结果封装为标准数据格式返回；
  • 若返回结果是对象，但不存在 status 属性，视为成功，将返回结果封装为标准数据格式返回；
  • 若返回结果是对象，且存在 status 属性，直接返回。

经过上述处理后，继续：

  • 若 status 为 200，取出 data 属性值返回；
  • 若 status 不为 200，取出 msg 属性值抛出错误。

# 客户端开发新接口时如何测试

自版本 1.11.0 开始，我们提供了 dcb.invokeNativeMethod 方法以直接调用原生方法，方便客户端开发新接口时调试：

dcb.invokeNativeMethod(
  // 要调用的原生方法名，字符串类型
  methodName: string,
  // 传给原生方法的参数，任意类型
  payload: any,
)

示例：

<html>
  <head>
    <script
      type="text/javascript"
      src="https://dcb-frontend.oss-cn-chengdu.aliyuncs.com/jssdk/lib/dcb@latest.js"
    ></script>
  </head>
  <body>
    <button onclick="handleTestClick()">测试调用原生方法</button>
    <script>
      window.handleTestClick = async function () {
        const res = await dcb.invokeNativeMethod('getAppInfo');
        console.log(res);
      };
    </script>
  </body>
</html>

# 小程序兼容设计

# 背景

某些 H5 项目要同时在多彩宝 App、小程序内使用，但其又调用了 App 专属的某些 JSSDK 方法，导致在小程序内不能直接使用。

因此，需要在 @dcb/jssdk 内部做些兼容，抹平这些差异。

# 实现

内部实现上尽量做到不依赖具体小程序，因此，需各小程序自行实现以下页面，在调用相关方法时会跳转到该页面：

页面路径 参数 说明
/pages/dcb-jssdk/navigateTo payload=<JSON 序列化后的传参> 该页面获取 payload 参数并做 JSON 解析后即得业务传给 dcb.navigateTo、dcb.navigateToWeb 的参数
上次更新时间: 6/17/2021, 4:58:18 PM