@docoi/mys-sdk 1.0.2 → 1.1.0

package/README.md

@@ -0,0 +1,212 @@
+# @docoi/mys-sdk
+
+H5 与梦游社 App 原生通信的 SDK。封装 JSBridge，对外提供类微信小程序风格的 API：全部 Promise 化，同时兼容 `success` / `fail` / `complete` 回调。
+
+- **类型完备** — 每个 API 都有类型声明与 JSDoc，IDE 里悬浮即可看到说明、最低可用版本和调用示例
+- **新旧通道自动兼容** — App 4.4.0 前后的通信方式不同，由 SDK 按各 API 的起始版本在内部选择，业务侧不需要判断版本
+- **零配置** — 不需要初始化，import 即用
+
+## 安装
+
+```bash
+pnpm add @docoi/mys-sdk
+```
+
+## 快速开始
+
+```ts
+import mys from '@docoi/mys-sdk'
+
+// 显示提示框
+await mys.showToast({ text: '操作成功' })
+
+// 获取系统信息
+const { result } = await mys.getSystemInfo()
+console.log(result.app_version, result.network_type)
+```
+
+## 引入方式
+
+两种写法等价，指向同一份实现，按团队习惯选一种：
+
+```ts
+// 聚合对象
+import mys from '@docoi/mys-sdk'
+await mys.showToast({ text: 'hi' })
+
+// 命名导入
+import { showToast } from '@docoi/mys-sdk'
+await showToast({ text: 'hi' })
+```
+
+## 返回值
+
+所有 API 返回 `Promise<NativeResponse<TResult>>`，`code` 为 `0` 才算成功：
+
+```ts
+interface NativeResponse<TResult> {
+  code: number // 0 表示成功
+  msg: string // 成功时固定为 'ok'
+  result: TResult // 业务数据
+}
+```
+
+```ts
+const res = await mys.chooseMedia({ count: 3 })
+console.log(res.result.tempFiles[0].tempFilePath)
+```
+
+## 错误处理
+
+失败时 Promise reject，同时触发 `fail` 和 `complete` 回调，拿到的是 `ApiError`：
+
+```ts
+interface ApiError {
+  errCode: number
+  errMsg: string // 形如 `showToast:fail parameter error: text is required`
+  errDetail?: unknown // 排查用的原始数据，仅部分场景存在
+}
+```
+
+```ts
+try {
+  await mys.getClipboardData()
+} catch (err) {
+  const { errCode, errMsg } = err as ApiError
+  console.error(errCode, errMsg)
+}
+```
+
+`errCode` 语义如下，常量可从 `@docoi/mys-sdk` 的 `constants/code` 导入：
+
+| 码   | 常量               | 含义                                             |
+| ---- | ------------------ | ------------------------------------------------ |
+| 0    | `SUCCESS`          | 成功                                             |
+| -1   | `SYSTEM_EXCEPTION` | 未知异常                                         |
+| 1001 | `METHOD_NOT_FOUND` | App 没有这个方法                                 |
+| 1002 | `PARAMS_ERROR`     | 参数校验失败，SDK 前置判定，不会发起调用         |
+| 2002 | `NOT_LOGGED_IN`    | 未登录、Token 失效                               |
+| 3002 | `PERMISSION_DENIED`| 权限被拒                                         |
+| 4002 | `NETWORK_ERROR`    | 网络异常                                         |
+| 5001 | `BRIDGE_ERROR`     | 通信链路不通：不在 App 内，或原生通道不存在      |
+| 5002 | `ENV_UNSUPPORTED`  | 当前 App 版本没有该能力，SDK 前置判定，不会发起调用 |
+| 9002 | `CUSTOM`           | 其他业务失败                                     |
+| 9101 | `RECORD_BUSY`      | 录音进行中，需要先调 `cancelRecordAudio`         |
+| 9102 | `RECORD_FAILED`    | 录音失败                                         |
+
+## 回调风格
+
+所有 API 都接受 `success` / `fail` / `complete`，与 Promise 同时生效：
+
+```ts
+mys.getSystemInfo({
+  success(res) {
+    console.log(res.result.app_version)
+  },
+  fail(err) {
+    console.error(err.errMsg)
+  },
+  complete(res) {
+    console.log('调用结束')
+  },
+})
+```
+
+## 事件监听
+
+监听类 API 用 `onXxx` 注册、`offXxx` 注销。回调直接收到原生事件的数据，不包装 `code` / `msg` / `result`：
+
+```ts
+mys.onKeyboardHeightChange((height) => {
+  console.log('键盘高度', height)
+})
+
+mys.offKeyboardHeightChange() // 不传参取消该事件下全部监听
+```
+
+只和某一次调用相关的事件，作为该次调用的参数传入，由 SDK 自动释放，不需要也不提供单独的 on/off：
+
+```ts
+await mys.shareWebCard({
+  title: '标题',
+  content: '内容',
+  icon: 'https://example.com/icon.png',
+  shareUrl: 'https://docoi.cc',
+  daokeUrl: 'daoke://page?type=5&h5Type=4&url=https://docoi.cc',
+  externalContent: '内容',
+  onShared: (res) => console.log('分享完成', res?.shareChannel),
+})
+
+await mys.startRecordAudio({
+  maxDuration: 60,
+  onProgress: ({ decibel }) => console.log('音量', decibel),
+  onEnd: ({ tempFilePath, duration, size }) => console.log(tempFilePath, duration, size),
+})
+```
+
+## API 一览
+
+| 分组         | API                                                                                                        |
+| ------------ | ---------------------------------------------------------------------------------------------------------- |
+| UI 交互      | `showToast` `triggerVibrate` `stopVibrate` `hideKeyboard` `onKeyboardHeightChange` / `offKeyboardHeightChange` `onCommentPanelChange` / `offCommentPanelChange` |
+| 媒体能力     | `previewImage` `previewVideo` `chooseMedia` `uploadFiles` `saveImageToPhotosAlbum` `startRecordAudio` `stopRecordAudio` `cancelRecordAudio` |
+| 设备能力     | `getSystemInfo` `setClipboardData` `getClipboardData` `checkPermission` `openPhoneSetting`                  |
+| 应用与页面   | `openApp` `swipeBack` `showPageName`                                                                       |
+| 页面生命周期 | `h5Loaded` `getBeforeInfo` `setBeforeInfo` `onPageShow` / `offPageShow` `onPageVisible` / `offPageVisible` `onPageInvisible` / `offPageInvisible` |
+| 页面跳转     | `switchTab` `navigateTo` `openWebview` `openInExternalBrowser` `closeWebView` `openScheme`                  |
+| 账号与用户   | `login` `getToken` `getCurrentCircleInfo`                                                                  |
+| 内容与分享   | `shareWebCard` `shareImage` `openAddCustomEmoji` `openCommentPanel` `showLongVipDesDialog` `voteAction` `openFriendsList` |
+| 业务场景     | `toBindGameRole` `bindGameRoleSuccess` `showAd` `onAdFinished` / `offAdFinished` `updateData` `openGiftBag` `onMemberActivate` / `offMemberActivate` |
+| 工具         | `setDebug` `registerNativeHandler`                                                                          |
+
+`getAppBaseInfo` / `isInApp` / `compareVersions` 用来读 App 环境信息，`ToastDuration` / `ShareType` 是枚举值。`onRoute` / `invokeDebug` 仅供仓库内的 Demo 调试，不承诺兼容，业务侧不要依赖。
+
+## App 版本兼容
+
+每个 API 的 JSDoc 里用 `@app` 标了最低可用版本。低于这个版本时：
+
+- **有旧接口的**（如 `login`、`showToast`、`previewImage`）由 SDK 自动改走旧通道，业务侧无感知
+- **没有旧接口的**（如 `chooseMedia`、`uploadFiles`、录音系列）直接以 `5002` 失败，不发起调用
+
+所以调用前一般不需要自己判断版本；确实要分支时用 `compareVersions`，它把入参与当前 App 版本比较（注意正负号与直觉相反）：
+
+```ts
+import { compareVersions } from '@docoi/mys-sdk'
+
+// compareVersions('4.4.0')：当前 App 版本更高返回 1，相等返回 0，更低返回 -1
+if (compareVersions('4.4.0') >= 0) {
+  await mys.uploadFiles({ files: ['mysFile://temp/xxx.png'] })
+}
+```
+
+## 运行环境
+
+- 产物语法基线 **ES2018**（Safari 12 / Chrome 63）。构建链会转译的可以直接用；直接引 CDN 或老构建链不转译 `node_modules` 时，需要自行保证运行时支持该基线
+- 必须在 App 的 WebView 内使用。浏览器里通信类 API 会以 `5001` 失败；页面跳转类会尝试唤起 App
+- 只提供 ESM 产物，不提供 CommonJS
+- 无第三方运行时依赖（`@docoi/jsbridge-sdk` 是唯一依赖）
+
+## TypeScript
+
+类型随包一起发布，参数和返回值都有提示：
+
+```ts
+import type { ShowToastParams, NativeResponse, ApiError } from '@docoi/mys-sdk'
+import { ToastDuration, ShareType } from '@docoi/mys-sdk'
+
+const params: ShowToastParams = { text: 'hi', duration: ToastDuration.Long }
+
+await mys.shareWebCard({
+  // ...
+  shareTypes: [ShareType.RecentContacts, ShareType.External],
+})
+```
+
+## 文档
+
+- API 文档站（测试环境）：<http://sdk-test.docoi.cc/mys-sdk/docs/>
+- 仓库与 Demo：[mys-sdk monorepo](../../README.md)
+
+## License
+
+MIT