@docoi/mys-sdk 1.2.0 → 1.2.2

package/README.md

@@ -1,212 +1,213 @@
-# @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` `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
+# @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 失效                               |
+| 3001 | `UNAUTHORIZED`     | 未授权的调用，没有通过 App 的安全校验            |
+| 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` |
+| 媒体能力     | `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` `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

package/dist/api/basic.d.ts

@@ -1,4 +1,4 @@
-import { OpenAppParams, ShowPageNameParams, SwipeBackParams, SetBeforeInfoParams, OpenAppResult, BeforeInfoResult, PageEventCallback, ShowToastParams, PlayMediaParams, ChooseMediaParams, ChooseMediaResult, UploadFilesParams, UploadFilesResult, SaveImageToPhotosAlbumParams, StartRecordAudioParams, SetClipboardDataParams, GetClipboardDataResult, TriggerVibrateParams, Callbacks, NativeResponse, SystemInfoResult, OpenPhoneSettingParams, CheckPermissionParams, CheckPermissionResult, KeyboardHeightChangeCallback, CommentPanelChangeCallback, EventListenOptions } from '../types';
+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';
 /**
  * 显示消息提示框。
  *
@@ -73,33 +73,6 @@ export declare function onKeyboardHeightChange(callback: KeyboardHeightChangeCal
  * mys.offKeyboardHeightChange()
  */
 export declare function offKeyboardHeightChange(callback?: KeyboardHeightChangeCallback): void;
-/**
- * 监听评论区面板状态变化，Native 评论区面板打开、关闭或状态变化时触发。
- *
- * @app 4.2.0
- * @example
- * mys.onCommentPanelChange((res) => {
- *   console.log('评论区面板状态:', res.visible, res.reason)
- * })
- *
- * // 只监听一次
- * mys.onCommentPanelChange((res) => {
- *   console.log('只监听一次:', res.visible, res.reason)
- * }, { once: true })
- *
- * // 取消监听
- * mys.offCommentPanelChange()
- */
-export declare function onCommentPanelChange(callback: CommentPanelChangeCallback, options?: EventListenOptions): void;
-/**
- * 取消监听评论区面板状态变化。
- *
- * @param callback 要取消的监听函数，不传则取消全部评论区面板监听
- * @app 4.2.0
- * @example
- * mys.offCommentPanelChange()
- */
-export declare function offCommentPanelChange(callback?: CommentPanelChangeCallback): void;
 /**
  * 预览图片。
  *
@@ -168,6 +141,21 @@ export declare function uploadFiles(params: UploadFilesParams): Promise<NativeRe
  * await mys.saveImageToPhotosAlbum({ filePath: canvas.toDataURL('image/png') })
  */
 export declare function saveImageToPhotosAlbum(params: SaveImageToPhotosAlbumParams): Promise<NativeResponse<void>>;
+/**
+ * 调起相机扫描二维码或条形码，返回识别出的内容。
+ *
+ * @note 需要相机权限，未授权时返回 3002，可先用 checkPermission 检查，再用 openPhoneSetting 引导用户开启。
+ * @note 用户取消扫码不算失败，成功返回且 cancelled 为 true，此时 result 为空字符串。
+ * @note 有画面但识别不出内容时 reject，errMsg 带原因。
+ *
+ * @app 待定
+ * @example
+ * const res = await mys.scanCode({ scanType: ['qrCode'] })
+ * if (!res.result.cancelled) {
+ *   console.log(res.result.result)
+ * }
+ */
+export declare function scanCode(params?: ScanCodeParams): Promise<NativeResponse<ScanCodeResult>>;
 /**
  * 开始录音，录音结果通过 onEnd 回调返回。
  *
@@ -270,6 +258,52 @@ export declare function checkPermission(params: CheckPermissionParams): Promise<
  * }
  */
 export declare function openPhoneSetting(params: OpenPhoneSettingParams): Promise<NativeResponse<void>>;
+/**
+ * 在 Native 存储里保存一个值，跨页面、跨 WebView 可读，App 卸载才清除。
+ *
+ * @note value 会序列化成 JSON 字符串后交给 Native，取回时还原成存入时的类型。
+ * @note undefined、函数、symbol 以及对象里的这些字段无法序列化，会被丢弃；顶层就是这些值时返回 1002。
+ * @note 每次读写都是一次 Native 往返，只适合存开关、上次选择这类少量状态，列表缓存等大块数据用 localStorage。
+ * @note 与 localStorage 互不相通：localStorage 随 WebView 回收丢失，且页面之间不共享。
+ *
+ * @app 待定
+ * @example
+ * await mys.setStorage({ key: 'bgm_enabled', value: true })
+ * await mys.setStorage({ key: 'last_choice', value: { id: 1, tags: ['a', 'b'] } })
+ */
+export declare function setStorage(params: SetStorageParams): Promise<NativeResponse<void>>;
+/**
+ * 读取 setStorage 保存的值。
+ *
+ * @note 键不存在时成功返回，data 为 null。
+ * @note 取回的文本不是合法 JSON（不是通过 setStorage 写入）时 reject。
+ *
+ * @app 待定
+ * @example
+ * const res = await mys.getStorage({ key: 'last_choice' })
+ * console.log(res.result.data)
+ */
+export declare function getStorage(params: GetStorageParams): Promise<NativeResponse<GetStorageResult>>;
+/**
+ * 删除 setStorage 保存的值。
+ *
+ * @note 键不存在时同样成功返回。
+ *
+ * @app 待定
+ * @example
+ * await mys.removeStorage({ key: 'last_choice' })
+ */
+export declare function removeStorage(params: RemoveStorageParams): Promise<NativeResponse<void>>;
+/**
+ * 清空 setStorage 保存的全部值。
+ *
+ * @note 只清除 SDK 写入的数据，不影响 App 自己的存储。
+ *
+ * @app 待定
+ * @example
+ * await mys.clearStorage()
+ */
+export declare function clearStorage(params?: Callbacks): Promise<NativeResponse<void>>;
 /**
  * 打开指定包名的其他 App（如游戏），未安装时触发下载。
  *
@@ -300,6 +334,108 @@ export declare function openApp(params?: OpenAppParams): Promise<NativeResponse<
  * await mys.swipeBack({ enable: false })
  */
 export declare function swipeBack(params: SwipeBackParams): Promise<NativeResponse<void>>;
+/**
+ * 设置当前页面是否允许原生下拉刷新。
+ *
+ * @note 只控制手势是否可用，不会立即触发刷新；触发刷新用 startPullDownRefresh，刷新由 onPullDownRefresh 通知。
+ * @note 只作用于当前页面，页面关闭后失效。
+ *
+ * @app 待定
+ * @example
+ * await mys.setPullDownRefresh({ enabled: true })
+ */
+export declare function setPullDownRefresh(params?: SetPullDownRefreshParams): Promise<NativeResponse<void>>;
+/**
+ * 主动触发一次下拉刷新，展示刷新动画并触发 onPullDownRefresh 的回调。
+ *
+ * @note 刷新完成后必须调用 stopPullDownRefresh，否则刷新动画不会收起。
+ *
+ * @app 待定
+ * @example
+ * await mys.startPullDownRefresh()
+ */
+export declare function startPullDownRefresh(params?: Callbacks): Promise<NativeResponse<void>>;
+/**
+ * 停止下拉刷新，收起刷新动画。
+ *
+ * @note 没有进行中的刷新时同样成功返回。
+ *
+ * @app 待定
+ * @example
+ * await mys.stopPullDownRefresh()
+ */
+export declare function stopPullDownRefresh(params?: Callbacks): Promise<NativeResponse<void>>;
+/**
+ * 监听下拉刷新，用户下拉或调用 startPullDownRefresh 时触发。
+ *
+ * @note 在回调里重新加载数据，完成后调用 stopPullDownRefresh 收起刷新动画。
+ *
+ * @app 待定
+ * @example
+ * mys.onPullDownRefresh(async () => {
+ *   await reload()
+ *   await mys.stopPullDownRefresh()
+ * })
+ */
+export declare function onPullDownRefresh(callback: PullDownRefreshCallback, options?: EventListenOptions): void;
+/**
+ * 取消监听下拉刷新。
+ *
+ * @param callback 要取消的监听函数，不传则取消全部下拉刷新监听
+ * @app 待定
+ * @example
+ * mys.offPullDownRefresh()
+ */
+export declare function offPullDownRefresh(callback?: PullDownRefreshCallback): void;
+/**
+ * 设置当前页面原生导航栏的标题。
+ *
+ * @note 只作用于当前页面，页面关闭后失效。
+ *
+ * @app 待定
+ * @example
+ * await mys.setNavigationBarTitle({ title: '活动详情' })
+ */
+export declare function setNavigationBarTitle(params: SetNavigationBarTitleParams): Promise<NativeResponse<void>>;
+/**
+ * 设置当前页面原生导航栏的背景色，以及标题和按钮的颜色。
+ *
+ * @note 只作用于当前页面，页面关闭后失效。
+ *
+ * @app 待定
+ * @example
+ * await mys.setNavigationBarColor({ backgroundColor: '#1a1a2e', frontColor: 'white' })
+ */
+export declare function setNavigationBarColor(params: SetNavigationBarColorParams): Promise<NativeResponse<void>>;
+/**
+ * 显示当前页面的原生导航栏。
+ *
+ * @app 待定
+ * @example
+ * await mys.showNavigationBar()
+ */
+export declare function showNavigationBar(params?: Callbacks): Promise<NativeResponse<void>>;
+/**
+ * 隐藏当前页面的原生导航栏。
+ *
+ * @note 隐藏后不会自动恢复，需要时调用 showNavigationBar。
+ *
+ * @app 待定
+ * @example
+ * await mys.hideNavigationBar()
+ */
+export declare function hideNavigationBar(params?: Callbacks): Promise<NativeResponse<void>>;
+/**
+ * 设置状态栏的文字颜色。
+ *
+ * @note 只改文字颜色，不改状态栏背景。
+ * @note 只作用于当前页面，页面关闭后失效。
+ *
+ * @app 待定
+ * @example
+ * await mys.setStatusBarStyle({ style: 'light' })
+ */
+export declare function setStatusBarStyle(params: SetStatusBarStyleParams): Promise<NativeResponse<void>>;
 /**
  * 告知 Native 当前 H5 页面的类型，用于 Native 侧的页面识别和埋点。
  *