@docoi/mys-sdk 1.2.1 → 1.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +213 -213
- package/dist/api/basic.d.ts +1 -28
- package/dist/api/biz.d.ts +12 -3
- package/dist/api/router/index.d.ts +1 -1
- package/dist/api/router/routes.d.ts +0 -2
- package/dist/bridge.d.ts +2 -1
- package/dist/index.mjs +516 -526
- package/dist/types/base.d.ts +18 -0
- package/dist/types/params.d.ts +3 -1
- package/dist/types/router.d.ts +2 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,213 +1,213 @@
|
|
|
1
|
-
# @docoi/mys-sdk
|
|
2
|
-
|
|
3
|
-
H5 与梦游社 App 原生通信的 SDK。封装 JSBridge，对外提供类微信小程序风格的 API：全部 Promise 化，同时兼容 `success` / `fail` / `complete` 回调。
|
|
4
|
-
|
|
5
|
-
- **类型完备** — 每个 API 都有类型声明与 JSDoc，IDE 里悬浮即可看到说明、最低可用版本和调用示例
|
|
6
|
-
- **新旧通道自动兼容** — App 4.4.0 前后的通信方式不同，由 SDK 按各 API 的起始版本在内部选择，业务侧不需要判断版本
|
|
7
|
-
- **零配置** — 不需要初始化，import 即用
|
|
8
|
-
|
|
9
|
-
## 安装
|
|
10
|
-
|
|
11
|
-
```bash
|
|
12
|
-
pnpm add @docoi/mys-sdk
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
## 快速开始
|
|
16
|
-
|
|
17
|
-
```ts
|
|
18
|
-
import mys from '@docoi/mys-sdk'
|
|
19
|
-
|
|
20
|
-
// 显示提示框
|
|
21
|
-
await mys.showToast({ text: '操作成功' })
|
|
22
|
-
|
|
23
|
-
// 获取系统信息
|
|
24
|
-
const { result } = await mys.getSystemInfo()
|
|
25
|
-
console.log(result.app_version, result.network_type)
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
## 引入方式
|
|
29
|
-
|
|
30
|
-
两种写法等价，指向同一份实现，按团队习惯选一种：
|
|
31
|
-
|
|
32
|
-
```ts
|
|
33
|
-
// 聚合对象
|
|
34
|
-
import mys from '@docoi/mys-sdk'
|
|
35
|
-
await mys.showToast({ text: 'hi' })
|
|
36
|
-
|
|
37
|
-
// 命名导入
|
|
38
|
-
import { showToast } from '@docoi/mys-sdk'
|
|
39
|
-
await showToast({ text: 'hi' })
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
## 返回值
|
|
43
|
-
|
|
44
|
-
所有 API 返回 `Promise<NativeResponse<TResult>>`，`code` 为 `0` 才算成功：
|
|
45
|
-
|
|
46
|
-
```ts
|
|
47
|
-
interface NativeResponse<TResult> {
|
|
48
|
-
code: number // 0 表示成功
|
|
49
|
-
msg: string // 成功时固定为 'ok'
|
|
50
|
-
result: TResult // 业务数据
|
|
51
|
-
}
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
```ts
|
|
55
|
-
const res = await mys.chooseMedia({ count: 3 })
|
|
56
|
-
console.log(res.result.tempFiles[0].tempFilePath)
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
## 错误处理
|
|
60
|
-
|
|
61
|
-
失败时 Promise reject，同时触发 `fail` 和 `complete` 回调，拿到的是 `ApiError`：
|
|
62
|
-
|
|
63
|
-
```ts
|
|
64
|
-
interface ApiError {
|
|
65
|
-
errCode: number
|
|
66
|
-
errMsg: string // 形如 `showToast:fail parameter error: text is required`
|
|
67
|
-
errDetail?: unknown // 排查用的原始数据，仅部分场景存在
|
|
68
|
-
}
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
```ts
|
|
72
|
-
try {
|
|
73
|
-
await mys.getClipboardData()
|
|
74
|
-
} catch (err) {
|
|
75
|
-
const { errCode, errMsg } = err as ApiError
|
|
76
|
-
console.error(errCode, errMsg)
|
|
77
|
-
}
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
`errCode` 语义如下，常量可从 `@docoi/mys-sdk` 的 `constants/code` 导入：
|
|
81
|
-
|
|
82
|
-
| 码 | 常量 | 含义 |
|
|
83
|
-
| ---- | ------------------ | ------------------------------------------------ |
|
|
84
|
-
| 0 | `SUCCESS` | 成功 |
|
|
85
|
-
| -1 | `SYSTEM_EXCEPTION` | 未知异常 |
|
|
86
|
-
| 1001 | `METHOD_NOT_FOUND` | App 没有这个方法 |
|
|
87
|
-
| 1002 | `PARAMS_ERROR` | 参数校验失败，SDK 前置判定，不会发起调用 |
|
|
88
|
-
| 2002 | `NOT_LOGGED_IN` | 未登录、Token 失效 |
|
|
89
|
-
| 3001 | `UNAUTHORIZED` | 未授权的调用，没有通过 App 的安全校验 |
|
|
90
|
-
| 3002 | `PERMISSION_DENIED`| 权限被拒 |
|
|
91
|
-
| 4002 | `NETWORK_ERROR` | 网络异常 |
|
|
92
|
-
| 5001 | `BRIDGE_ERROR` | 通信链路不通：不在 App 内，或原生通道不存在 |
|
|
93
|
-
| 5002 | `ENV_UNSUPPORTED` | 当前 App 版本没有该能力，SDK 前置判定，不会发起调用 |
|
|
94
|
-
| 9002 | `CUSTOM` | 其他业务失败 |
|
|
95
|
-
| 9101 | `RECORD_BUSY` | 录音进行中，需要先调 `cancelRecordAudio` |
|
|
96
|
-
| 9102 | `RECORD_FAILED` | 录音失败 |
|
|
97
|
-
|
|
98
|
-
## 回调风格
|
|
99
|
-
|
|
100
|
-
所有 API 都接受 `success` / `fail` / `complete`，与 Promise 同时生效：
|
|
101
|
-
|
|
102
|
-
```ts
|
|
103
|
-
mys.getSystemInfo({
|
|
104
|
-
success(res) {
|
|
105
|
-
console.log(res.result.app_version)
|
|
106
|
-
},
|
|
107
|
-
fail(err) {
|
|
108
|
-
console.error(err.errMsg)
|
|
109
|
-
},
|
|
110
|
-
complete(res) {
|
|
111
|
-
console.log('调用结束')
|
|
112
|
-
},
|
|
113
|
-
})
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
## 事件监听
|
|
117
|
-
|
|
118
|
-
监听类 API 用 `onXxx` 注册、`offXxx` 注销。回调直接收到原生事件的数据，不包装 `code` / `msg` / `result`：
|
|
119
|
-
|
|
120
|
-
```ts
|
|
121
|
-
mys.onKeyboardHeightChange((height) => {
|
|
122
|
-
console.log('键盘高度', height)
|
|
123
|
-
})
|
|
124
|
-
|
|
125
|
-
mys.offKeyboardHeightChange() // 不传参取消该事件下全部监听
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
只和某一次调用相关的事件，作为该次调用的参数传入，由 SDK 自动释放，不需要也不提供单独的 on/off：
|
|
129
|
-
|
|
130
|
-
```ts
|
|
131
|
-
await mys.shareWebCard({
|
|
132
|
-
title: '标题',
|
|
133
|
-
content: '内容',
|
|
134
|
-
icon: 'https://example.com/icon.png',
|
|
135
|
-
shareUrl: 'https://docoi.cc',
|
|
136
|
-
daokeUrl: 'daoke://page?type=5&h5Type=4&url=https://docoi.cc',
|
|
137
|
-
externalContent: '内容',
|
|
138
|
-
onShared: (res) => console.log('分享完成', res?.shareChannel),
|
|
139
|
-
})
|
|
140
|
-
|
|
141
|
-
await mys.startRecordAudio({
|
|
142
|
-
maxDuration: 60,
|
|
143
|
-
onProgress: ({ decibel }) => console.log('音量', decibel),
|
|
144
|
-
onEnd: ({ tempFilePath, duration, size }) => console.log(tempFilePath, duration, size),
|
|
145
|
-
})
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
## API 一览
|
|
149
|
-
|
|
150
|
-
| 分组 | API |
|
|
151
|
-
| ------------ | ---------------------------------------------------------------------------------------------------------- |
|
|
152
|
-
| UI 交互 | `showToast` `triggerVibrate` `stopVibrate` `hideKeyboard` `onKeyboardHeightChange` / `offKeyboardHeightChange`
|
|
153
|
-
| 媒体能力 | `previewImage` `previewVideo` `chooseMedia` `uploadFiles` `saveImageToPhotosAlbum` `startRecordAudio` `stopRecordAudio` `cancelRecordAudio` |
|
|
154
|
-
| 设备能力 | `getSystemInfo` `setClipboardData` `getClipboardData` `checkPermission` `openPhoneSetting` |
|
|
155
|
-
| 应用与页面 | `openApp` `swipeBack` `showPageName` |
|
|
156
|
-
| 页面生命周期 | `h5Loaded` `getBeforeInfo` `setBeforeInfo` `onPageShow` / `offPageShow` `onPageVisible` / `offPageVisible` `onPageInvisible` / `offPageInvisible` |
|
|
157
|
-
| 页面跳转 | `switchTab` `navigateTo` `openWebview` `openInExternalBrowser` `closeWebView` `openScheme` |
|
|
158
|
-
| 账号与用户 | `login` `getToken` `getCurrentCircleInfo` |
|
|
159
|
-
| 内容与分享 | `shareWebCard` `shareImage` `openAddCustomEmoji` `openCommentPanel` `showLongVipDesDialog` `voteAction` `openFriendsList` |
|
|
160
|
-
| 业务场景 | `toBindGameRole` `bindGameRoleSuccess` `showAd` `updateData` `openGiftBag` `onMemberActivate` / `offMemberActivate` |
|
|
161
|
-
| 工具 | `setDebug` `registerNativeHandler` |
|
|
162
|
-
|
|
163
|
-
`getAppBaseInfo` / `isInApp` / `compareVersions` 用来读 App 环境信息，`ToastDuration` / `ShareType` 是枚举值。`onRoute` / `invokeDebug` 仅供仓库内的 Demo 调试，不承诺兼容，业务侧不要依赖。
|
|
164
|
-
|
|
165
|
-
## App 版本兼容
|
|
166
|
-
|
|
167
|
-
每个 API 的 JSDoc 里用 `@app` 标了最低可用版本。低于这个版本时：
|
|
168
|
-
|
|
169
|
-
- **有旧接口的**（如 `login`、`showToast`、`previewImage`）由 SDK 自动改走旧通道，业务侧无感知
|
|
170
|
-
- **没有旧接口的**（如 `chooseMedia`、`uploadFiles`、录音系列）直接以 `5002` 失败，不发起调用
|
|
171
|
-
|
|
172
|
-
所以调用前一般不需要自己判断版本；确实要分支时用 `compareVersions`，它把入参与当前 App 版本比较（注意正负号与直觉相反）：
|
|
173
|
-
|
|
174
|
-
```ts
|
|
175
|
-
import { compareVersions } from '@docoi/mys-sdk'
|
|
176
|
-
|
|
177
|
-
// compareVersions('4.4.0')：当前 App 版本更高返回 1，相等返回 0，更低返回 -1
|
|
178
|
-
if (compareVersions('4.4.0') >= 0) {
|
|
179
|
-
await mys.uploadFiles({ files: ['mysFile://temp/xxx.png'] })
|
|
180
|
-
}
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
## 运行环境
|
|
184
|
-
|
|
185
|
-
- 产物语法基线 **ES2018**（Safari 12 / Chrome 63）。构建链会转译的可以直接用；直接引 CDN 或老构建链不转译 `node_modules` 时，需要自行保证运行时支持该基线
|
|
186
|
-
- 必须在 App 的 WebView 内使用。浏览器里通信类 API 会以 `5001` 失败；页面跳转类会尝试唤起 App
|
|
187
|
-
- 只提供 ESM 产物，不提供 CommonJS
|
|
188
|
-
- 无第三方运行时依赖（`@docoi/jsbridge-sdk` 是唯一依赖）
|
|
189
|
-
|
|
190
|
-
## TypeScript
|
|
191
|
-
|
|
192
|
-
类型随包一起发布，参数和返回值都有提示：
|
|
193
|
-
|
|
194
|
-
```ts
|
|
195
|
-
import type { ShowToastParams, NativeResponse, ApiError } from '@docoi/mys-sdk'
|
|
196
|
-
import { ToastDuration, ShareType } from '@docoi/mys-sdk'
|
|
197
|
-
|
|
198
|
-
const params: ShowToastParams = { text: 'hi', duration: ToastDuration.Long }
|
|
199
|
-
|
|
200
|
-
await mys.shareWebCard({
|
|
201
|
-
// ...
|
|
202
|
-
shareTypes: [ShareType.RecentContacts, ShareType.External],
|
|
203
|
-
})
|
|
204
|
-
```
|
|
205
|
-
|
|
206
|
-
## 文档
|
|
207
|
-
|
|
208
|
-
- API 文档站（测试环境）：<http://sdk-test.docoi.cc/mys-sdk/docs/>
|
|
209
|
-
- 仓库与 Demo：[mys-sdk monorepo](../../README.md)
|
|
210
|
-
|
|
211
|
-
## License
|
|
212
|
-
|
|
213
|
-
MIT
|
|
1
|
+
# @docoi/mys-sdk
|
|
2
|
+
|
|
3
|
+
H5 与梦游社 App 原生通信的 SDK。封装 JSBridge，对外提供类微信小程序风格的 API：全部 Promise 化，同时兼容 `success` / `fail` / `complete` 回调。
|
|
4
|
+
|
|
5
|
+
- **类型完备** — 每个 API 都有类型声明与 JSDoc，IDE 里悬浮即可看到说明、最低可用版本和调用示例
|
|
6
|
+
- **新旧通道自动兼容** — App 4.4.0 前后的通信方式不同，由 SDK 按各 API 的起始版本在内部选择，业务侧不需要判断版本
|
|
7
|
+
- **零配置** — 不需要初始化，import 即用
|
|
8
|
+
|
|
9
|
+
## 安装
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
pnpm add @docoi/mys-sdk
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## 快速开始
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
import mys from '@docoi/mys-sdk'
|
|
19
|
+
|
|
20
|
+
// 显示提示框
|
|
21
|
+
await mys.showToast({ text: '操作成功' })
|
|
22
|
+
|
|
23
|
+
// 获取系统信息
|
|
24
|
+
const { result } = await mys.getSystemInfo()
|
|
25
|
+
console.log(result.app_version, result.network_type)
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## 引入方式
|
|
29
|
+
|
|
30
|
+
两种写法等价，指向同一份实现，按团队习惯选一种：
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
// 聚合对象
|
|
34
|
+
import mys from '@docoi/mys-sdk'
|
|
35
|
+
await mys.showToast({ text: 'hi' })
|
|
36
|
+
|
|
37
|
+
// 命名导入
|
|
38
|
+
import { showToast } from '@docoi/mys-sdk'
|
|
39
|
+
await showToast({ text: 'hi' })
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## 返回值
|
|
43
|
+
|
|
44
|
+
所有 API 返回 `Promise<NativeResponse<TResult>>`，`code` 为 `0` 才算成功：
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
interface NativeResponse<TResult> {
|
|
48
|
+
code: number // 0 表示成功
|
|
49
|
+
msg: string // 成功时固定为 'ok'
|
|
50
|
+
result: TResult // 业务数据
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
const res = await mys.chooseMedia({ count: 3 })
|
|
56
|
+
console.log(res.result.tempFiles[0].tempFilePath)
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## 错误处理
|
|
60
|
+
|
|
61
|
+
失败时 Promise reject，同时触发 `fail` 和 `complete` 回调，拿到的是 `ApiError`：
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
interface ApiError {
|
|
65
|
+
errCode: number
|
|
66
|
+
errMsg: string // 形如 `showToast:fail parameter error: text is required`
|
|
67
|
+
errDetail?: unknown // 排查用的原始数据，仅部分场景存在
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
try {
|
|
73
|
+
await mys.getClipboardData()
|
|
74
|
+
} catch (err) {
|
|
75
|
+
const { errCode, errMsg } = err as ApiError
|
|
76
|
+
console.error(errCode, errMsg)
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
`errCode` 语义如下，常量可从 `@docoi/mys-sdk` 的 `constants/code` 导入：
|
|
81
|
+
|
|
82
|
+
| 码 | 常量 | 含义 |
|
|
83
|
+
| ---- | ------------------ | ------------------------------------------------ |
|
|
84
|
+
| 0 | `SUCCESS` | 成功 |
|
|
85
|
+
| -1 | `SYSTEM_EXCEPTION` | 未知异常 |
|
|
86
|
+
| 1001 | `METHOD_NOT_FOUND` | App 没有这个方法 |
|
|
87
|
+
| 1002 | `PARAMS_ERROR` | 参数校验失败，SDK 前置判定，不会发起调用 |
|
|
88
|
+
| 2002 | `NOT_LOGGED_IN` | 未登录、Token 失效 |
|
|
89
|
+
| 3001 | `UNAUTHORIZED` | 未授权的调用，没有通过 App 的安全校验 |
|
|
90
|
+
| 3002 | `PERMISSION_DENIED`| 权限被拒 |
|
|
91
|
+
| 4002 | `NETWORK_ERROR` | 网络异常 |
|
|
92
|
+
| 5001 | `BRIDGE_ERROR` | 通信链路不通：不在 App 内，或原生通道不存在 |
|
|
93
|
+
| 5002 | `ENV_UNSUPPORTED` | 当前 App 版本没有该能力，SDK 前置判定，不会发起调用 |
|
|
94
|
+
| 9002 | `CUSTOM` | 其他业务失败 |
|
|
95
|
+
| 9101 | `RECORD_BUSY` | 录音进行中，需要先调 `cancelRecordAudio` |
|
|
96
|
+
| 9102 | `RECORD_FAILED` | 录音失败 |
|
|
97
|
+
|
|
98
|
+
## 回调风格
|
|
99
|
+
|
|
100
|
+
所有 API 都接受 `success` / `fail` / `complete`，与 Promise 同时生效：
|
|
101
|
+
|
|
102
|
+
```ts
|
|
103
|
+
mys.getSystemInfo({
|
|
104
|
+
success(res) {
|
|
105
|
+
console.log(res.result.app_version)
|
|
106
|
+
},
|
|
107
|
+
fail(err) {
|
|
108
|
+
console.error(err.errMsg)
|
|
109
|
+
},
|
|
110
|
+
complete(res) {
|
|
111
|
+
console.log('调用结束')
|
|
112
|
+
},
|
|
113
|
+
})
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
## 事件监听
|
|
117
|
+
|
|
118
|
+
监听类 API 用 `onXxx` 注册、`offXxx` 注销。回调直接收到原生事件的数据，不包装 `code` / `msg` / `result`：
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
mys.onKeyboardHeightChange((height) => {
|
|
122
|
+
console.log('键盘高度', height)
|
|
123
|
+
})
|
|
124
|
+
|
|
125
|
+
mys.offKeyboardHeightChange() // 不传参取消该事件下全部监听
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
只和某一次调用相关的事件，作为该次调用的参数传入，由 SDK 自动释放，不需要也不提供单独的 on/off：
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
await mys.shareWebCard({
|
|
132
|
+
title: '标题',
|
|
133
|
+
content: '内容',
|
|
134
|
+
icon: 'https://example.com/icon.png',
|
|
135
|
+
shareUrl: 'https://docoi.cc',
|
|
136
|
+
daokeUrl: 'daoke://page?type=5&h5Type=4&url=https://docoi.cc',
|
|
137
|
+
externalContent: '内容',
|
|
138
|
+
onShared: (res) => console.log('分享完成', res?.shareChannel),
|
|
139
|
+
})
|
|
140
|
+
|
|
141
|
+
await mys.startRecordAudio({
|
|
142
|
+
maxDuration: 60,
|
|
143
|
+
onProgress: ({ decibel }) => console.log('音量', decibel),
|
|
144
|
+
onEnd: ({ tempFilePath, duration, size }) => console.log(tempFilePath, duration, size),
|
|
145
|
+
})
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## API 一览
|
|
149
|
+
|
|
150
|
+
| 分组 | API |
|
|
151
|
+
| ------------ | ---------------------------------------------------------------------------------------------------------- |
|
|
152
|
+
| UI 交互 | `showToast` `triggerVibrate` `stopVibrate` `hideKeyboard` `onKeyboardHeightChange` / `offKeyboardHeightChange` |
|
|
153
|
+
| 媒体能力 | `previewImage` `previewVideo` `chooseMedia` `uploadFiles` `saveImageToPhotosAlbum` `startRecordAudio` `stopRecordAudio` `cancelRecordAudio` |
|
|
154
|
+
| 设备能力 | `getSystemInfo` `setClipboardData` `getClipboardData` `checkPermission` `openPhoneSetting` |
|
|
155
|
+
| 应用与页面 | `openApp` `swipeBack` `showPageName` |
|
|
156
|
+
| 页面生命周期 | `h5Loaded` `getBeforeInfo` `setBeforeInfo` `onPageShow` / `offPageShow` `onPageVisible` / `offPageVisible` `onPageInvisible` / `offPageInvisible` |
|
|
157
|
+
| 页面跳转 | `switchTab` `navigateTo` `openWebview` `openInExternalBrowser` `closeWebView` `openScheme` |
|
|
158
|
+
| 账号与用户 | `login` `getToken` `getCurrentCircleInfo` |
|
|
159
|
+
| 内容与分享 | `shareWebCard` `shareImage` `openAddCustomEmoji` `openCommentPanel` `showLongVipDesDialog` `voteAction` `openFriendsList` |
|
|
160
|
+
| 业务场景 | `toBindGameRole` `bindGameRoleSuccess` `showAd` `updateData` `openGiftBag` `onMemberActivate` / `offMemberActivate` |
|
|
161
|
+
| 工具 | `setDebug` `registerNativeHandler` |
|
|
162
|
+
|
|
163
|
+
`getAppBaseInfo` / `isInApp` / `compareVersions` 用来读 App 环境信息，`ToastDuration` / `ShareType` 是枚举值。`onRoute` / `invokeDebug` 仅供仓库内的 Demo 调试，不承诺兼容，业务侧不要依赖。
|
|
164
|
+
|
|
165
|
+
## App 版本兼容
|
|
166
|
+
|
|
167
|
+
每个 API 的 JSDoc 里用 `@app` 标了最低可用版本。低于这个版本时：
|
|
168
|
+
|
|
169
|
+
- **有旧接口的**（如 `login`、`showToast`、`previewImage`）由 SDK 自动改走旧通道，业务侧无感知
|
|
170
|
+
- **没有旧接口的**（如 `chooseMedia`、`uploadFiles`、录音系列）直接以 `5002` 失败，不发起调用
|
|
171
|
+
|
|
172
|
+
所以调用前一般不需要自己判断版本；确实要分支时用 `compareVersions`，它把入参与当前 App 版本比较（注意正负号与直觉相反）：
|
|
173
|
+
|
|
174
|
+
```ts
|
|
175
|
+
import { compareVersions } from '@docoi/mys-sdk'
|
|
176
|
+
|
|
177
|
+
// compareVersions('4.4.0')：当前 App 版本更高返回 1，相等返回 0，更低返回 -1
|
|
178
|
+
if (compareVersions('4.4.0') >= 0) {
|
|
179
|
+
await mys.uploadFiles({ files: ['mysFile://temp/xxx.png'] })
|
|
180
|
+
}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## 运行环境
|
|
184
|
+
|
|
185
|
+
- 产物语法基线 **ES2018**（Safari 12 / Chrome 63）。构建链会转译的可以直接用；直接引 CDN 或老构建链不转译 `node_modules` 时，需要自行保证运行时支持该基线
|
|
186
|
+
- 必须在 App 的 WebView 内使用。浏览器里通信类 API 会以 `5001` 失败；页面跳转类会尝试唤起 App
|
|
187
|
+
- 只提供 ESM 产物，不提供 CommonJS
|
|
188
|
+
- 无第三方运行时依赖（`@docoi/jsbridge-sdk` 是唯一依赖）
|
|
189
|
+
|
|
190
|
+
## TypeScript
|
|
191
|
+
|
|
192
|
+
类型随包一起发布，参数和返回值都有提示：
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
import type { ShowToastParams, NativeResponse, ApiError } from '@docoi/mys-sdk'
|
|
196
|
+
import { ToastDuration, ShareType } from '@docoi/mys-sdk'
|
|
197
|
+
|
|
198
|
+
const params: ShowToastParams = { text: 'hi', duration: ToastDuration.Long }
|
|
199
|
+
|
|
200
|
+
await mys.shareWebCard({
|
|
201
|
+
// ...
|
|
202
|
+
shareTypes: [ShareType.RecentContacts, ShareType.External],
|
|
203
|
+
})
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
## 文档
|
|
207
|
+
|
|
208
|
+
- API 文档站（测试环境）：<http://sdk-test.docoi.cc/mys-sdk/docs/>
|
|
209
|
+
- 仓库与 Demo：[mys-sdk monorepo](../../README.md)
|
|
210
|
+
|
|
211
|
+
## License
|
|
212
|
+
|
|
213
|
+
MIT
|
package/dist/api/basic.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { OpenAppParams, ShowPageNameParams, SwipeBackParams, SetBeforeInfoParams, OpenAppResult, BeforeInfoResult, PageEventCallback, ShowToastParams, PlayMediaParams, ChooseMediaParams, ChooseMediaResult, UploadFilesParams, UploadFilesResult, SaveImageToPhotosAlbumParams, StartRecordAudioParams, SetClipboardDataParams, GetClipboardDataResult, ScanCodeParams, ScanCodeResult, SetPullDownRefreshParams, PullDownRefreshCallback, SetNavigationBarTitleParams, SetNavigationBarColorParams, SetStatusBarStyleParams, SetStorageParams, GetStorageParams, GetStorageResult, RemoveStorageParams, TriggerVibrateParams, Callbacks, NativeResponse, SystemInfoResult, OpenPhoneSettingParams, CheckPermissionParams, CheckPermissionResult, KeyboardHeightChangeCallback,
|
|
1
|
+
import { OpenAppParams, ShowPageNameParams, SwipeBackParams, SetBeforeInfoParams, OpenAppResult, BeforeInfoResult, PageEventCallback, ShowToastParams, PlayMediaParams, ChooseMediaParams, ChooseMediaResult, UploadFilesParams, UploadFilesResult, SaveImageToPhotosAlbumParams, StartRecordAudioParams, SetClipboardDataParams, GetClipboardDataResult, ScanCodeParams, ScanCodeResult, SetPullDownRefreshParams, PullDownRefreshCallback, SetNavigationBarTitleParams, SetNavigationBarColorParams, SetStatusBarStyleParams, SetStorageParams, GetStorageParams, GetStorageResult, RemoveStorageParams, TriggerVibrateParams, Callbacks, NativeResponse, SystemInfoResult, OpenPhoneSettingParams, CheckPermissionParams, CheckPermissionResult, KeyboardHeightChangeCallback, EventListenOptions } from '../types';
|
|
2
2
|
/**
|
|
3
3
|
* 显示消息提示框。
|
|
4
4
|
*
|
|
@@ -73,33 +73,6 @@ export declare function onKeyboardHeightChange(callback: KeyboardHeightChangeCal
|
|
|
73
73
|
* mys.offKeyboardHeightChange()
|
|
74
74
|
*/
|
|
75
75
|
export declare function offKeyboardHeightChange(callback?: KeyboardHeightChangeCallback): void;
|
|
76
|
-
/**
|
|
77
|
-
* 监听评论区面板状态变化，Native 评论区面板打开、关闭或状态变化时触发。
|
|
78
|
-
*
|
|
79
|
-
* @app 4.2.0
|
|
80
|
-
* @example
|
|
81
|
-
* mys.onCommentPanelChange((res) => {
|
|
82
|
-
* console.log('评论区面板状态:', res.visible, res.reason)
|
|
83
|
-
* })
|
|
84
|
-
*
|
|
85
|
-
* // 只监听一次
|
|
86
|
-
* mys.onCommentPanelChange((res) => {
|
|
87
|
-
* console.log('只监听一次:', res.visible, res.reason)
|
|
88
|
-
* }, { once: true })
|
|
89
|
-
*
|
|
90
|
-
* // 取消监听
|
|
91
|
-
* mys.offCommentPanelChange()
|
|
92
|
-
*/
|
|
93
|
-
export declare function onCommentPanelChange(callback: CommentPanelChangeCallback, options?: EventListenOptions): void;
|
|
94
|
-
/**
|
|
95
|
-
* 取消监听评论区面板状态变化。
|
|
96
|
-
*
|
|
97
|
-
* @param callback 要取消的监听函数，不传则取消全部评论区面板监听
|
|
98
|
-
* @app 4.2.0
|
|
99
|
-
* @example
|
|
100
|
-
* mys.offCommentPanelChange()
|
|
101
|
-
*/
|
|
102
|
-
export declare function offCommentPanelChange(callback?: CommentPanelChangeCallback): void;
|
|
103
76
|
/**
|
|
104
77
|
* 预览图片。
|
|
105
78
|
*
|
package/dist/api/biz.d.ts
CHANGED
|
@@ -32,7 +32,7 @@ export declare function getCurrentCircleInfo(params?: Callbacks<GetCircleInfoRes
|
|
|
32
32
|
*
|
|
33
33
|
* @note 响应只表示分享面板已唤起，不包含分享结果；用户完成分享后通过 onShared 回调通知，不需要单独监听事件。
|
|
34
34
|
* @note activityDetail 传对象时会序列化为 JSON 字符串后下发；trackData 需自行 JSON.stringify。
|
|
35
|
-
* @note onShared、getSharePictureUrl
|
|
35
|
+
* @note onShared、getSharePictureUrl 不需要手动取消，调用失败或下一次调用 shareWebCard 时自动取消；onShared 触发一次后也会取消，getSharePictureUrl 不受影响。
|
|
36
36
|
* @note 每次调用都会重新注册 getSharePictureUrl，截图结果的缓存要放在函数外面（页面级变量），否则每次分享都会重新截图。
|
|
37
37
|
*
|
|
38
38
|
* @app 2.9.0
|
|
@@ -90,11 +90,20 @@ export declare function openAddCustomEmoji(params?: Callbacks): Promise<NativeRe
|
|
|
90
90
|
/**
|
|
91
91
|
* 打开动态评论区面板。
|
|
92
92
|
*
|
|
93
|
-
* @note
|
|
93
|
+
* @note 面板打开、关闭等状态变化通过 onChange 回调通知，不需要单独监听事件。
|
|
94
|
+
* @note onChange 不需要手动取消，调用失败或下一次调用 openCommentPanel 时自动取消；面板关闭后不取消，同一次打开可能多次触发。
|
|
94
95
|
*
|
|
95
96
|
* @app 4.2.0
|
|
96
97
|
* @example
|
|
97
|
-
* await mys.openCommentPanel({
|
|
98
|
+
* await mys.openCommentPanel({
|
|
99
|
+
* serverId: 's123',
|
|
100
|
+
* dynamicId: 'd456',
|
|
101
|
+
* autoFocusInput: true,
|
|
102
|
+
* onChange: (res) => {
|
|
103
|
+
* // 面板关闭后刷新评论数
|
|
104
|
+
* if (!res.visible) refreshCommentCount()
|
|
105
|
+
* },
|
|
106
|
+
* })
|
|
98
107
|
*/
|
|
99
108
|
export declare function openCommentPanel(params: OpenCommentPanelParams): Promise<NativeResponse<void>>;
|
|
100
109
|
/**
|
|
@@ -43,7 +43,7 @@ export declare function switchTab(params: SwitchTabParams): Promise<NativeRespon
|
|
|
43
43
|
* mys.navigateTo({ type: 'userHomePage', params: { userId } }) // 用户主页
|
|
44
44
|
* mys.navigateTo({ type: 'groupChatPage', params: { serverId, groupId } }) // 群聊
|
|
45
45
|
* mys.navigateTo({ type: 'joinGroupPage', params: { inviteCode } }) // 查询小群并加入
|
|
46
|
-
* mys.navigateTo({ type: 'privateChatPage', params: { userId
|
|
46
|
+
* mys.navigateTo({ type: 'privateChatPage', params: { userId } }) // 私聊（4.1.0 起）
|
|
47
47
|
* mys.navigateTo({ type: 'myPublishPage' }) // 我的-发布
|
|
48
48
|
* mys.navigateTo({ type: 'myFavoritePage' }) // 我的-收藏（3.8.0 起）
|
|
49
49
|
* mys.navigateTo({ type: 'browseHistoryPage' }) // 浏览记录（4.4.0 起）
|
|
@@ -235,7 +235,6 @@ export declare const PAGE_ROUTES: {
|
|
|
235
235
|
};
|
|
236
236
|
nickName: {
|
|
237
237
|
key: string;
|
|
238
|
-
required: true;
|
|
239
238
|
};
|
|
240
239
|
};
|
|
241
240
|
};
|
|
@@ -629,7 +628,6 @@ export declare const ROUTES: {
|
|
|
629
628
|
};
|
|
630
629
|
nickName: {
|
|
631
630
|
key: string;
|
|
632
|
-
required: true;
|
|
633
631
|
};
|
|
634
632
|
};
|
|
635
633
|
};
|
package/dist/bridge.d.ts
CHANGED
|
@@ -17,13 +17,14 @@ export declare function listen<T = unknown>(event: string, callback: (payload: T
|
|
|
17
17
|
export declare function unlisten(event: string, callback?: object): void;
|
|
18
18
|
/**
|
|
19
19
|
* 注册供 Native 调用的方法，按 since 选择通道，返回注销该次注册的函数。
|
|
20
|
-
*
|
|
20
|
+
* 两个通道回给 Native 的结构一致（NativeHandlerReply）：旧通道由 transport/legacy.ts 包装，新通道由 registerNativeHandler 包装。
|
|
21
21
|
*/
|
|
22
22
|
export declare function registerHandler<TData = unknown, TResult = unknown>(name: string, handler: NativeHandler<TData, TResult>, since?: string): () => void;
|
|
23
23
|
/** 取消 registerHandler 注册的方法，通道选择规则与注册时一致 */
|
|
24
24
|
export declare function unregisterHandler(name: string, since?: string): void;
|
|
25
25
|
/**
|
|
26
26
|
* 注册供 Native 调用的方法，固定走新通道，返回注销该次注册的函数。
|
|
27
|
+
* 处理函数的结果按旧通道的结构包装后回给 Native：成功 `{ success: true, data }`，失败 `{ success: false, error: { message } }`。
|
|
27
28
|
*
|
|
28
29
|
* @note 需要按 App 版本选择通道时用 registerHandler。
|
|
29
30
|
*/
|