@docoi/mys-sdk 1.2.0 → 1.2.2

package/dist/types/base.d.ts

@@ -115,6 +115,24 @@ export interface RouteInfo {
 }
 /** Native 调 H5 注册的方法的处理函数 */
 export type NativeHandler<TData = unknown, TResult = unknown> = (data: TData) => TResult | Promise<TResult>;
+/** H5 注册的方法执行失败时回给 Native 的原因 */
+export interface NativeHandlerError {
+    /** 只有旧通道「方法未注册」时为 -1，其余失败不带 */
+    code?: number;
+    /** 失败原因 */
+    message: string;
+}
+/**
+ * H5 注册的方法回给 Native 的数据，新旧两个通道一致，沿用旧版 jsbridge 的结构：Native 按 success 判断成败。
+ * 不用 `{ code, msg, result }`：Native 不解析这种结构，返回的数据会取不到。
+ */
+export type NativeHandlerReply = {
+    success: true;
+    data: unknown;
+} | {
+    success: false;
+    error: NativeHandlerError;
+};
 /** listen 的选项 */
 export interface ListenOptions<T = unknown> {
     /** 支持新通道的最低 App 版本，低于该版本走旧通道 jsbridge；不传则始终走新通道 mysJSBridge */

package/dist/types/enums.d.ts

@@ -23,6 +23,12 @@ export type PermissionType = "camera" | "microphone" | "location" | "storage" |
 export type PermissionStatus = "granted" | "denied" | "permanentlyDenied";
 /** 摄像头方向 */
 export type CameraDirection = "back" | "front";
+/** 扫码支持识别的码类型 */
+export type ScanType = "qrCode" | "barCode";
+/** 导航栏标题和按钮的颜色 */
+export type NavigationBarFrontColor = "white" | "black";
+/** 状态栏文字颜色 */
+export type StatusBarStyle = "light" | "dark";
 /** Webview 容器类型（daoke type 5 的 h5Type） */
 export type WebviewType = "normal" | "mini" | "immersive";
 /** Webview 扩展类型 */

package/dist/types/params.d.ts

@@ -1,6 +1,6 @@
 import { Callbacks } from './base';
-import { MediaFileType, SettingType, CameraDirection, PermissionType, ShareContentType, ToastDuration, UpdateDataType, ShareType } from './enums';
-import { ChooseMediaResult, CheckPermissionResult, ShareImageResult, UploadFilesProgressCallback, UploadFilesResult, VoteData, OpenAppResult, OpenFriendsListResult, RecordAudioEndCallback, RecordAudioProgressCallback, SharedCallback, SharePictureUrlHandler, AdFinishedCallback, GiftSentCallback } from './results';
+import { MediaFileType, NavigationBarFrontColor, ScanType, StatusBarStyle, SettingType, CameraDirection, PermissionType, ShareContentType, ToastDuration, UpdateDataType, ShareType } from './enums';
+import { ChooseMediaResult, CheckPermissionResult, GetStorageResult, ScanCodeResult, ShareImageResult, UploadFilesProgressCallback, UploadFilesResult, VoteData, OpenAppResult, OpenFriendsListResult, RecordAudioEndCallback, RecordAudioProgressCallback, SharedCallback, SharePictureUrlHandler, AdFinishedCallback, GiftSentCallback, CommentPanelChangeCallback } from './results';
 /** 事件监听选项 */
 export interface EventListenOptions {
     /** 是否只监听一次，触发后自动取消监听 */
@@ -19,14 +19,32 @@ export interface ShowToastParams extends Callbacks {
 }
 /** openPhoneSetting 参数 */
 export interface OpenPhoneSettingParams extends Callbacks {
-    /** 要打开的系统设置页类型，取值与 checkPermission 的 permission 一致 */
+    /**
+     * 要打开的系统设置页类型，取值与 checkPermission 的 permission 一致
+     *
+     * 可选值：
+     * - 'camera'：相机
+     * - 'microphone'：麦克风
+     * - 'location'：定位
+     * - 'storage'：存储
+     * - 'notification'：通知
+     */
     permission: SettingType;
 }
 /**
  * checkPermission 参数
  */
 export interface CheckPermissionParams extends Callbacks<CheckPermissionResult> {
-    /** 要检查的权限类型 */
+    /**
+     * 要检查的权限类型
+     *
+     * 可选值：
+     * - 'camera'：相机
+     * - 'microphone'：麦克风
+     * - 'location'：地理位置
+     * - 'storage'：存储空间
+     * - 'notification'：通知
+     */
     permission: PermissionType;
 }
 /**
@@ -55,6 +73,10 @@ export interface ChooseMediaParams extends Callbacks<ChooseMediaResult> {
     /**
      * 选择或拍摄的媒体类型。
      *
+     * 可选值：
+     * - 'image'：图片
+     * - 'video'：视频
+     *
      * @default 'image'
      */
     mediaType?: MediaFileType;
@@ -73,6 +95,10 @@ export interface ChooseMediaParams extends Callbacks<ChooseMediaResult> {
     /**
      * 默认摄像头。
      *
+     * 可选值：
+     * - 'back'：后置摄像头
+     * - 'front'：前置摄像头
+     *
      * @default 'back'
      */
     camera?: CameraDirection;
@@ -104,6 +130,80 @@ export interface StartRecordAudioParams extends Callbacks {
     /** 录音音量回调，录音期间持续触发，只对本次录音有效；触发频率由宿主 App 决定 */
     onProgress?: RecordAudioProgressCallback;
 }
+/** setStorage 参数 */
+export interface SetStorageParams extends Callbacks {
+    /** 键名，不能为空字符串；SDK 会统一加 web_ 前缀，不需要自己加 */
+    key: string;
+    /** 要存储的值，可以是对象、数组、字符串、数字、布尔值；取回时类型与存入时一致 */
+    value: unknown;
+}
+/** getStorage 参数 */
+export interface GetStorageParams extends Callbacks<GetStorageResult> {
+    /** 键名，不能为空字符串；SDK 会统一加 web_ 前缀，不需要自己加 */
+    key: string;
+}
+/** removeStorage 参数 */
+export interface RemoveStorageParams extends Callbacks {
+    /** 键名，不能为空字符串；SDK 会统一加 web_ 前缀，不需要自己加 */
+    key: string;
+}
+/** scanCode 参数 */
+export interface ScanCodeParams extends Callbacks<ScanCodeResult> {
+    /**
+     * 要识别的码类型，不传则两种都识别。
+     *
+     * 可选值：
+     * - 'qrCode'：二维码
+     * - 'barCode'：条形码
+     *
+     * @default ['qrCode', 'barCode']
+     */
+    scanType?: ScanType[];
+    /**
+     * 是否只允许相机扫码，不提供从相册选图识别的入口。
+     *
+     * @default false
+     */
+    onlyFromCamera?: boolean;
+}
+/** setPullDownRefresh 参数 */
+export interface SetPullDownRefreshParams extends Callbacks {
+    /**
+     * 是否允许下拉刷新。
+     *
+     * @default true
+     */
+    enabled?: boolean;
+}
+/** setNavigationBarTitle 参数 */
+export interface SetNavigationBarTitleParams extends Callbacks {
+    /** 导航栏标题，允许空字符串 */
+    title: string;
+}
+/** setNavigationBarColor 参数 */
+export interface SetNavigationBarColorParams extends Callbacks {
+    /** 导航栏背景色，格式为 #RRGGBB */
+    backgroundColor: string;
+    /**
+     * 导航栏标题和按钮的颜色
+     *
+     * 可选值：
+     * - 'white'：白色
+     * - 'black'：黑色
+     */
+    frontColor: NavigationBarFrontColor;
+}
+/** setStatusBarStyle 参数 */
+export interface SetStatusBarStyleParams extends Callbacks {
+    /**
+     * 状态栏文字颜色
+     *
+     * 可选值：
+     * - 'light'：白色文字，用于深色背景
+     * - 'dark'：黑色文字，用于浅色背景
+     */
+    style: StatusBarStyle;
+}
 /** setClipboardData 参数 */
 export interface SetClipboardDataParams extends Callbacks {
     /** 剪贴板内容，允许空字符串 */
@@ -192,7 +292,14 @@ export interface ShareWebCardParams extends Callbacks {
     daokeUrl: string;
     /** 指定分享的频道 ID，英文逗号分隔，serverId 不为空时才有效 */
     channelIds?: string;
-    /** 分享内容类型 */
+    /**
+     * 分享内容类型
+     *
+     * 可选值：
+     * - 1：动态（普通动态、wiki、通关分享）
+     * - 2：外部分享口令
+     * - 3：战报分享（客户端展示特殊样式）
+     */
     contentType?: ShareContentType;
     /** 动态详情，长文动态分享时传给客户端做动态相关操作，传对象时 SDK 会序列化为 JSON 字符串后下发 */
     activityDetail?: string | Record<string, unknown>;
@@ -251,6 +358,8 @@ export interface OpenCommentPanelParams extends Callbacks {
     commentId?: string;
     /** 打开后是否自动聚焦输入框 */
     autoFocusInput?: boolean;
+    /** 评论区面板打开、关闭或状态变化时的回调，只对本次调用生效 */
+    onChange?: CommentPanelChangeCallback;
 }
 /** voteAction 参数：当前投票数据加上被点击的选项下标 */
 export interface VoteActionParams extends VoteData, Callbacks<VoteData> {
@@ -275,7 +384,24 @@ export interface OpenFriendsListParams extends Callbacks<OpenFriendsListResult>
 }
 /** updateData 参数 */
 export interface UpdateDataParams extends Callbacks {
-    /** 更新的数据类型，各类型含义和对应的 params 结构见可选值说明 */
+    /**
+     * 更新的数据类型，各类型含义和对应的 params 结构见可选值说明
+     *
+     * 可选值：
+     * - 1：关闭首页新春活动 icon
+     * - 2：更新头像框，params 为 { type, url }，type 1 佩戴 2 取消佩戴，url 为头像框链接
+     * - 3：更新 App 首页当前选中圈子数据
+     * - 4：首页积分任务奖励领取完成
+     * - 5：平台任务奖励领取完成
+     * - 6：背包红点消除
+     * - 7：兑换码红点消除
+     * - 8：更新徽章，params 为 { type, url }，type 1 佩戴 2 取消佩戴，url 为徽章链接
+     * - 9：刷新 App 首页所有数据
+     * - 10：刷新 App 首页 VIP 入口红点，params 为 { server_id }
+     * - 11：更新聊天气泡，params 为 { type, left_android, right_android, left_ios, right_ios, color }，type 1 佩戴 2 取消佩戴
+     * - 12：会员大厅领取会员礼包、平台权益，全部领取完成
+     * - 13：更新用户基础信息，params 为 { nick_name, gender, avatar, update_type }，update_type 1 表示来自 MBTI 的更新
+     */
     type: UpdateDataType;
     /** 附带参数，结构随 type 变化，不需要参数的类型可省略 */
     params?: Record<string, unknown>;

package/dist/types/results.d.ts

@@ -1,4 +1,4 @@
-import { PermissionStatus, PermissionType, ShareImageAction } from './enums';
+import { PermissionStatus, PermissionType, ScanType, ShareImageAction } from './enums';
 /** chooseMedia 返回值 */
 export interface ChooseMediaResult {
     /** 本地临时媒体文件列表 */
@@ -55,6 +55,28 @@ export interface UploadFilesProgressFile {
  * @param progress 本次上传各文件的进度
  */
 export type UploadFilesProgressCallback = (progress: UploadFilesProgress) => void;
+/** scanCode 返回值 */
+export interface ScanCodeResult {
+    /** 识别出的文本内容；用户取消扫码时为空字符串 */
+    result: string;
+    /**
+     * 实际识别到的码类型；用户取消扫码时不返回
+     *
+     * 可选值：
+     * - 'qrCode'：二维码
+     * - 'barCode'：条形码
+     */
+    scanType?: ScanType;
+    /** 用户是否取消了扫码 */
+    cancelled: boolean;
+}
+/** 下拉刷新触发回调，在回调里重新加载数据，完成后必须调用 stopPullDownRefresh 收起刷新动画 */
+export type PullDownRefreshCallback = () => void;
+/** getStorage 返回值 */
+export interface GetStorageResult {
+    /** 取回的值，类型与存入时一致；键不存在时为 null */
+    data: unknown;
+}
 /** getClipboardData 返回值 */
 export interface GetClipboardDataResult {
     /** 剪贴板内容 */
@@ -113,9 +135,25 @@ export interface SystemInfoResult extends Partial<AppBaseInfo> {
 }
 /** checkPermission 返回值 */
 export interface CheckPermissionResult {
-    /** 权限类型 */
+    /**
+     * 权限类型
+     *
+     * 可选值：
+     * - 'camera'：相机
+     * - 'microphone'：麦克风
+     * - 'location'：地理位置
+     * - 'storage'：存储空间
+     * - 'notification'：通知
+     */
     permission: PermissionType;
-    /** 权限检查结果 */
+    /**
+     * 权限检查结果
+     *
+     * 可选值：
+     * - 'granted'：已授权
+     * - 'denied'：已拒绝
+     * - 'permanentlyDenied'：永久拒绝
+     */
     result: PermissionStatus;
 }
 /** openApp 返回值 */
@@ -188,7 +226,16 @@ export interface GetTokenResult {
 }
 /** shareImage 返回值 */
 export interface ShareImageResult {
-    /** 用户在分享弹窗中点击的操作 */
+    /**
+     * 用户在分享弹窗中点击的操作
+     *
+     * 可选值：
+     * - 'wechat'：微信好友
+     * - 'moment'：微信朋友圈
+     * - 'qq'：QQ 好友
+     * - 'save'：保存图片
+     * - 'cancel'：取消
+     */
     readonly action: ShareImageAction;
 }
 /** getCurrentCircleInfo 返回值 */

package/dist/types/router.d.ts

@@ -11,14 +11,29 @@ export interface LaunchCallbacks extends Callbacks {
 }
 /** switchTab 参数 */
 export interface SwitchTabParams extends LaunchCallbacks {
-    /** 目标底部 tab */
+    /**
+     * 目标底部 tab
+     *
+     * 可选值：
+     * - 'home'：首页
+     * - 'discover'：发现
+     * - 'message'：消息
+     * - 'mine'：我的
+     */
     tab: TabBarType;
     /** 附加参数 */
     params?: SwitchTabExtraParams;
 }
 /** switchTab 附加参数 */
 export interface SwitchTabExtraParams {
-    /** 发现页二级 tab，仅 tab 为 discover 时有效 */
+    /**
+     * 发现页二级 tab，仅 tab 为 discover 时有效
+     *
+     * 可选值：
+     * - 'friends'：好友圈
+     * - 'square'：广场
+     * - 'comic'：漫剧
+     */
     subTab?: DiscoverSubTab;
     /** 是否来自 MBTI 分享页 */
     fromMbtiShare?: boolean;
@@ -30,6 +45,13 @@ export interface OpenWebviewParams extends LaunchCallbacks {
     /**
      * 容器类型，用外部浏览器打开请用 openInExternalBrowser。
      *
+     * 可选值：
+     * - 'normal'：普通 H5，带原生导航栏
+     * - 'mini'：小程序样式
+     * - 'immersive'：沉浸式
+     * - 'dynamic'：动态链接
+     * - 'transparent'：纯透明 H5，App 3.8.0+，url 需为 https，不支持 params
+     *
      * @default 'normal'
      */
     type?: WebviewType | WebviewExtType;
@@ -61,7 +83,20 @@ export interface DynamicPublishPageParams {
     serverId: string | number;
     /** 频道 ID，传入后自动选中该频道 */
     channelId?: string | number;
-    /** 发布类型，App 4.4.0 以下不生效 */
+    /**
+     * 发布类型，App 4.4.0 以下不生效
+     *
+     * 可选值：
+     * - 1：攻略
+     * - 2：公告
+     * - 3：问答
+     * - 4：投票
+     * - 5：通关分享
+     * - 6：wiki
+     * - 7：广场
+     * - 8：短剧
+     * - 9：视频
+     */
     publishType?: PublishType;
 }
 /** 点赞列表 */
@@ -77,9 +112,30 @@ export interface CircleHomePageParams {
     serverId: string | number;
     /** 进入后执行的操作：publish 为发布动态 */
     action?: "publish";
-    /** 发布类型，action 为 publish 时生效，App 4.4.0 以下不生效 */
+    /**
+     * 发布类型，action 为 publish 时生效，App 4.4.0 以下不生效
+     *
+     * 可选值：
+     * - 1：攻略
+     * - 2：公告
+     * - 3：问答
+     * - 4：投票
+     * - 5：通关分享
+     * - 6：wiki
+     * - 7：广场
+     * - 8：短剧
+     * - 9：视频
+     */
     publishType?: PublishType;
-    /** 关系操作 */
+    /**
+     * 关系操作
+     *
+     * 可选值：
+     * - 'apprentice'：拜师
+     * - 'graduate'：出师
+     * - 'intimacyShare'：亲密度分享
+     * - 'takeApprentice'：收徒
+     */
     relationType?: CircleRelationType;
     /** 图片链接 */
     imageUrl?: string;
@@ -93,7 +149,13 @@ export interface JoinCirclePageParams {
 }
 /** 新版首页 */
 export interface HomePageParams {
-    /** 顶部 tab，不传则不指定 */
+    /**
+     * 顶部 tab，不传则不指定
+     *
+     * 可选值：
+     * - 'official'：官方推荐
+     * - 'community'：玩家社区
+     */
     tab?: HomeTab;
     /** 圈子（服务器）ID，不传则停留在当前首页圈子，App 4.4.0 起支持 */
     serverId?: string | number;
@@ -139,12 +201,18 @@ export interface JoinGroupPageParams {
 export interface PrivateChatPageParams {
     /** 对方用户 ID */
     userId: string | number;
-    /** 对方昵称 */
-    nickName: string;
+    /** 对方昵称，为空时不下发 */
+    nickName?: string;
 }
 /** 活动中心 */
 export interface ActivityCenterPageParams {
-    /** 默认选中的 tab */
+    /**
+     * 默认选中的 tab
+     *
+     * 可选值：
+     * - 'welfare'：福利
+     * - 'activity'：活动
+     */
     tab?: ActivityCenterTab;
 }
 /** 广告 SDK 页面 */
@@ -163,7 +231,16 @@ export interface BindGamePageParams {
 export interface PlayerReportPageParams {
     /** 被举报对象的 ID，随 objectType 变化：用户 ID、评论 ID、动态 ID 等 */
     objectId: string | number;
-    /** 被举报对象的类型 */
+    /**
+     * 被举报对象的类型
+     *
+     * 可选值：
+     * - 'user'：用户
+     * - 'circle'：服务器（圈子）
+     * - 'comment'：评论
+     * - 'trends'：动态
+     * - 'message'：消息
+     */
     objectType: ReportObjectType;
     /** 会话 ID，举报会话时需要 */
     conversationId?: string | number;

package/dist/utils/data.d.ts

@@ -1,5 +1,5 @@
 /**
- * 数据处理工具：类型判断、容错解析、错误原因提取，以及发往 Native 前的数据规整。
+ * 数据处理工具：类型判断、容错解析、错误原因提取，Native 传入数据的还原，以及发往 Native 前的数据规整。
  * 原生已有的（Array.isArray、Number.isFinite、Number.isInteger）不再包装；仅 SDK 内部使用，不从 index.ts 导出。
  *
  * 规整的背景：iOS 的 postMessage 对消息体做结构化克隆，Vue 响应式 Proxy 无法克隆（抛 DataCloneError），
@@ -29,6 +29,12 @@ export declare function safeDecode(value: string): string;
  * 两个通道的失败都要转成 errMsg，只此一份实现，避免同一类失败在两个通道上说法不同。
  */
 export declare function getErrorReason(err: unknown): string;
+/**
+ * 还原 Native 传入的一层数据：同一个对象 iOS 传对象，Android 可能先序列化成 JSON 文本。
+ * 只有解析结果是纯对象才还原，数值、数字串、数组 JSON、普通文本都原样返回；
+ * 不递归，更深层的字符串字段是业务数据（如 getStorage 的 data），不能动。
+ */
+export declare function fromNative(value: unknown): unknown;
 /** 规整失败时抛出，带上字段名，由调用方转成参数错误 */
 export declare class PlainDataError extends Error {
 }
@@ -37,3 +43,8 @@ export declare class PlainDataError extends Error {
  * 循环引用、BigInt、Map、Set、二进制数据会抛 PlainDataError。
  */
 export declare function toPlainData(data: unknown): unknown;
+/**
+ * 把任意值序列化成 JSON 字符串，拦截规则同 toPlainData，且根值也检查（根值可能就是 Map、Set）。
+ * 返回 undefined 表示值本身没有 JSON 表示（undefined、函数、symbol）。
+ */
+export declare function toJsonString(data: unknown): string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docoi/mys-sdk",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "基于 JSBridge 封装的H5 SDK，统一 Native 通信与业务 API 封装",
   "author": "tanyangkang",
   "license": "MIT",