@docoi/mys-sdk 1.1.0 → 1.2.1

package/README.md

@@ -86,6 +86,7 @@ try {
 | 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 内，或原生通道不存在      |
@@ -156,7 +157,7 @@ await mys.startRecordAudio({
 | 页面跳转     | `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` |
+| 业务场景     | `toBindGameRole` `bindGameRoleSuccess` `showAd` `updateData` `openGiftBag` `onMemberActivate` / `offMemberActivate` |
 | 工具         | `setDebug` `registerNativeHandler`                                                                          |
 
 `getAppBaseInfo` / `isInApp` / `compareVersions` 用来读 App 环境信息，`ToastDuration` / `ShareType` 是枚举值。`onRoute` / `invokeDebug` 仅供仓库内的 Demo 调试，不承诺兼容，业务侧不要依赖。

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, CommentPanelChangeCallback, EventListenOptions } from '../types';
 /**
  * 显示消息提示框。
  *
@@ -168,6 +168,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 +285,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 +361,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 侧的页面识别和埋点。
  *

package/dist/api/biz.d.ts

@@ -1,4 +1,4 @@
-import { Callbacks, NativeResponse, EventListenOptions, ShareWebCardParams, ShareImageParams, ShareImageResult, ShowAdParams, BindGameRoleParams, OpenCommentPanelParams, VoteActionParams, OpenGiftBagParams, OpenFriendsListParams, OpenFriendsListResult, UpdateDataParams, LoginResult, GetTokenResult, GetCircleInfoResult, VoteData, AdFinishedCallback, MemberActivateHandler } from '../types';
+import { Callbacks, NativeResponse, ShareWebCardParams, ShareImageParams, ShareImageResult, ShowAdParams, BindGameRoleParams, OpenCommentPanelParams, VoteActionParams, OpenGiftBagParams, OpenFriendsListParams, OpenFriendsListResult, UpdateDataParams, LoginResult, GetTokenResult, GetCircleInfoResult, VoteData, MemberActivateHandler } from '../types';
 /**
  * 登录授权。
  *
@@ -147,32 +147,20 @@ export declare function bindGameRoleSuccess(params?: Callbacks): Promise<NativeR
 /**
  * 展示原生广告视频。
  *
- * @note 广告播放完成后 Native 通过 onAdFinished 事件通知。
+ * @note 广告播放完成后通过 onFinished 回调通知，不需要单独监听事件；只有 Native 回传的 module 与 params.module 一致时才触发。
+ * @note onFinished 不需要手动取消，触发一次后自动取消；同一个 module 只保留最近一次调用的 onFinished，不同 module 互不影响，调用失败也不会取消。
  *
  * @app 3.9.0
  * @example
- * await mys.showAd({ type: 1, params: { circle_id: '123', module: 1 } })
- */
-export declare function showAd(params: ShowAdParams): Promise<NativeResponse<void>>;
-/**
- * 监听广告播放完成。
- *
- * @app 3.7.0
- * @example
- * mys.onAdFinished((res) => {
- *   console.log(res.module)
+ * await mys.showAd({
+ *   type: 1,
+ *   params: { circle_id: '123', module: 1 },
+ *   onFinished: (res) => {
+ *     console.log('广告播放完成', res.module)
+ *   },
  * })
  */
-export declare function onAdFinished(callback: AdFinishedCallback, options?: EventListenOptions): void;
-/**
- * 取消监听广告播放完成。
- *
- * @param callback 要取消的监听函数，不传则取消全部广告播放完成监听
- * @app 3.7.0
- * @example
- * mys.offAdFinished()
- */
-export declare function offAdFinished(callback?: AdFinishedCallback): void;
+export declare function showAd(params: ShowAdParams): Promise<NativeResponse<void>>;
 /**
  * 通知 Native 更新数据。
  *
@@ -185,9 +173,19 @@ export declare function updateData(params: UpdateDataParams): Promise<NativeResp
 /**
  * 打开客户端背包。
  *
+ * @note 送礼成功后通过 onSent 回调通知，不需要单独监听事件。
+ * @note onSent 不需要手动取消，调用失败或下一次调用 openGiftBag 时自动取消；每次送礼成功都会触发。
+ *
  * @app 3.2.0
  * @example
- * await mys.openGiftBag({ user_id: 'u1', server_id: 's123', openBag: true })
+ * await mys.openGiftBag({
+ *   user_id: 'u1',
+ *   server_id: 's123',
+ *   openBag: true,
+ *   onSent: (res) => {
+ *     console.log('送礼成功', res.gift_id, res.gift_name)
+ *   },
+ * })
  */
 export declare function openGiftBag(params: OpenGiftBagParams): Promise<NativeResponse<void>>;
 /**

package/dist/api/router/index.d.ts

@@ -9,6 +9,12 @@ import { Callbacks, NativeResponse, NavigateToParams, OpenInExternalBrowserParam
  * @app 4.4.0
  * @example
  * await mys.switchTab({ tab: 'discover', params: { subTab: 'square' } })
+ *
+ * // 各 tab
+ * mys.switchTab({ tab: 'home' })     // 首页
+ * mys.switchTab({ tab: 'discover' }) // 发现，可用 params.subTab 指定二级 tab：friends 好友圈、square 广场、comic 漫剧
+ * mys.switchTab({ tab: 'message' })  // 消息
+ * mys.switchTab({ tab: 'mine' })     // 我的
  */
 export declare function switchTab(params: SwitchTabParams): Promise<NativeResponse<void>>;
 /**
@@ -16,13 +22,42 @@ export declare function switchTab(params: SwitchTabParams): Promise<NativeRespon
  *
  * @note 不在 App 内时唤起 App，唤起失败（超时仍停留在当前页）时触发 onLaunchFail，由业务侧引导下载。
  * @note 唤起 App 和 App 4.4.0 以下的跳转都是发出即成功，不代表页面已打开。
- * @note App 4.4.0 以下能否跳转取决于目标页面自己的起始版本，不支持的返回 ENV_UNSUPPORTED（5002）；绑定游戏角色、添加自定义表情页面在低版本仍可用。
+ * @note App 4.4.0 以下能否跳转取决于目标页面自己的起始版本，不支持的返回 ENV_UNSUPPORTED（5002）；动态发布、资料编辑、点赞列表、广告页、绑定游戏角色、添加自定义表情页面在低版本仍可用。
  *
  * @app 4.4.0
  * @paramsMap NavigatePageParamsMap
  * @example
  * await mys.navigateTo({ type: 'userHomePage', params: { userId: '123' } })
  * await mys.navigateTo({ url: 'daoke://page?type=11&user_id=123' })
+ *
+ * // 各页面及必填参数；行尾标了版本的页面，App 低于该版本返回 5002
+ * mys.navigateTo({ type: 'dynamicDetailPage', params: { dynamicId } })                     // 动态详情
+ * mys.navigateTo({ type: 'dynamicPublishPage', params: { serverId } })                     // 动态发布
+ * mys.navigateTo({ type: 'topicPage', params: { topicId } })                               // 动态话题
+ * mys.navigateTo({ type: 'likeListPage', params: { dynamicId, publishType } })             // 点赞列表
+ * mys.navigateTo({ type: 'circleHomePage', params: { serverId } })                         // 圈子主页
+ * mys.navigateTo({ type: 'joinCirclePage', params: { serverId, inviteCode } })             // 查询圈子并加入
+ * mys.navigateTo({ type: 'homePage' })                                                     // 新版首页
+ * mys.navigateTo({ type: 'guideCatalogPage', params: { serverId, channelId, catalogId } }) // 攻略一级分类
+ * mys.navigateTo({ type: 'gamePushSettingPage', params: { serverId } })                    // 游戏离线推送开关
+ * mys.navigateTo({ type: 'userHomePage', params: { userId } })                             // 用户主页
+ * mys.navigateTo({ type: 'groupChatPage', params: { serverId, groupId } })                 // 群聊
+ * mys.navigateTo({ type: 'joinGroupPage', params: { inviteCode } })                        // 查询小群并加入
+ * mys.navigateTo({ type: 'privateChatPage', params: { userId, nickName } })                // 私聊（4.1.0 起）
+ * mys.navigateTo({ type: 'myPublishPage' })                                                // 我的-发布
+ * mys.navigateTo({ type: 'myFavoritePage' })                                               // 我的-收藏（3.8.0 起）
+ * mys.navigateTo({ type: 'browseHistoryPage' })                                            // 浏览记录（4.4.0 起）
+ * mys.navigateTo({ type: 'profileEditPage' })                                              // 资料编辑
+ * mys.navigateTo({ type: 'coinRechargePage' })                                             // 金币充值
+ * mys.navigateTo({ type: 'gameSubscribePage' })                                            // 游戏消息订阅（3.8.0 起）
+ * mys.navigateTo({ type: 'douyinMallPage' })                                               // 抖音商城
+ * mys.navigateTo({ type: 'activityCenterPage' })                                           // 活动中心（3.9.0 起）
+ * mys.navigateTo({ type: 'adPage', params: { url } })                                      // 广告 SDK 页面
+ * mys.navigateTo({ type: 'coinDetailPage' })                                               // 金币明细
+ * mys.navigateTo({ type: 'miniGamesPage' })                                                // 小游戏集合（一起玩）
+ * mys.navigateTo({ type: 'bindGamePage', params: { serverId, gameName } })                 // 绑定游戏角色
+ * mys.navigateTo({ type: 'playerReportPage', params: { objectId, objectType } })           // 玩家举报（4.4.0 起）
+ * mys.navigateTo({ type: 'addCustomEmojiPage' })                                           // 添加自定义表情
  */
 export declare function navigateTo(params: NavigateToParams): Promise<NativeResponse<void>>;
 /**
@@ -35,6 +70,13 @@ export declare function navigateTo(params: NavigateToParams): Promise<NativeResp
  * @app 4.4.0
  * @example
  * await mys.openWebview({ url: 'https://example.com', type: 'immersive' })
+ *
+ * // 各容器类型
+ * mys.openWebview({ url, type: 'normal' })      // 普通 H5，带原生导航栏
+ * mys.openWebview({ url, type: 'mini' })        // 小程序样式
+ * mys.openWebview({ url, type: 'immersive' })   // 沉浸式，没有原生导航栏
+ * mys.openWebview({ url, type: 'dynamic' })     // 动态链接
+ * mys.openWebview({ url, type: 'transparent' }) // 纯透明 H5，url 需为 https，不支持 params（3.8.0 起）
  */
 export declare function openWebview(params: OpenWebviewParams): Promise<NativeResponse<void>>;
 /**

package/dist/api/router/routes.d.ts

@@ -68,6 +68,9 @@ export declare const PAGE_ROUTES: {
                     publish: string;
                 };
             };
+            publishType: {
+                key: string;
+            };
             relationType: {
                 key: string;
                 enum: {
@@ -333,6 +336,23 @@ export declare const PAGE_ROUTES: {
         since: string;
         fields: {};
     };
+    dynamicPublishPage: {
+        type: number;
+        name: string;
+        since: string;
+        fields: {
+            serverId: {
+                key: string;
+                required: true;
+            };
+            channelId: {
+                key: string;
+            };
+            publishType: {
+                key: string;
+            };
+        };
+    };
 };
 /** navigateTo 页面 + switchTab / openWebview 的路由，key 为语义名 */
 export declare const ROUTES: {
@@ -442,6 +462,9 @@ export declare const ROUTES: {
                     publish: string;
                 };
             };
+            publishType: {
+                key: string;
+            };
             relationType: {
                 key: string;
                 enum: {
@@ -707,6 +730,23 @@ export declare const ROUTES: {
         since: string;
         fields: {};
     };
+    dynamicPublishPage: {
+        type: number;
+        name: string;
+        since: string;
+        fields: {
+            serverId: {
+                key: string;
+                required: true;
+            };
+            channelId: {
+                key: string;
+            };
+            publishType: {
+                key: string;
+            };
+        };
+    };
 };
 export type RouteKey = keyof typeof ROUTES;
 /** daoke type → 路由，未登记的 type 返回 undefined */

package/dist/constants/code.d.ts

@@ -13,6 +13,8 @@ export declare const METHOD_NOT_FOUND = 1001;
 export declare const PARAMS_ERROR = 1002;
 /** 未登录段起点：未登录、Token 失效、Token 过期等。 */
 export declare const NOT_LOGGED_IN = 2002;
+/** 未授权的调用：调用方没有通过 App 的安全校验，App 拒绝执行。与 PERMISSION_DENIED 不同，不是系统权限或用户授权的问题。 */
+export declare const UNAUTHORIZED = 3001;
 /** 权限拒绝段起点：权限被拒、权限未开通、用户拒绝授权等。 */
 export declare const PERMISSION_DENIED = 3002;
 /** 网络错误段起点：网络异常、服务端 5xx、超时等。 */