@docoi/mys-sdk 1.0.2 → 1.1.0

package/dist/api/basic.d.ts

@@ -1,24 +1,19 @@
-import { ShowToastParams, PlayMediaParams, ChooseMediaParams, ChooseMediaResult, UploadFilesParams, UploadFilesResult, SaveImageToPhotosAlbumParams, SaveVideoToPhotosAlbumParams, StartRecordParams, SetClipboardDataParams, GetClipboardDataResult, OpenInExternalBrowserParams, TriggerVibrateParams, Callbacks, NativeResponse, SystemInfoResult, NetworkTypeResult, 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, TriggerVibrateParams, Callbacks, NativeResponse, SystemInfoResult, OpenPhoneSettingParams, CheckPermissionParams, CheckPermissionResult, KeyboardHeightChangeCallback, CommentPanelChangeCallback, EventListenOptions } from '../types';
 /**
  * 显示消息提示框。
  *
- * @note
- * text 不能为空。
- * duration 默认 ToastDuration.Short，0 表示短时显示，1 表示长时显示。
+ * @note App 4.4.0 以下只支持 text，duration 不生效。
  *
- * @app 3.0.0
+ * @app 3.6.0
  * @example
  * await mys.showToast({ text: '操作成功' })
  */
 export declare function showToast(params: ShowToastParams): Promise<NativeResponse<void>>;
 /**
- * 触发原生震动反馈。
+ * 触发原生震动反馈，支持单段震动、多段变力度震动和循环震动。
  *
- * 支持单段震动、多段变力度震动和循环震动。执行优先级为：有 steps 时走多段震动；无 steps 且有 duration 时走单段震动；两者都没有时由宿主 App 决定默认震动行为。
- *
- * @note
- * iOS 如果不支持自定义力度和精确时长，intensity 和 duration 会被忽略，退化为系统默认触感节奏。
- * repeat 为 true 时会无限循环，需调用 stopVibrate 停止。
+ * @note 执行优先级：有 steps 时走多段震动；无 steps 且有 duration 时走单段震动；两者都没有时由宿主 App 决定默认震动行为。
+ * @note iOS 如果不支持自定义力度和精确时长，intensity 和 duration 会被忽略，退化为系统默认触感节奏。
  *
  * @app 4.1.0
  * @example
@@ -34,9 +29,7 @@ export declare function showToast(params: ShowToastParams): Promise<NativeRespon
  */
 export declare function triggerVibrate(params?: TriggerVibrateParams): Promise<NativeResponse<void>>;
 /**
- * 停止原生震动反馈。
- *
- * 用于停止 triggerVibrate 发起的循环震动。
+ * 停止原生震动反馈，用于停止 triggerVibrate 发起的循环震动。
  *
  * @app 4.1.0
  * @example
@@ -46,55 +39,42 @@ export declare function stopVibrate(params?: Callbacks): Promise<NativeResponse<
 /**
  * 收起当前 WebView 中已弹出的系统软键盘。
  *
- * @note
- * 该 API 仅用于请求隐藏键盘，不用于主动显示键盘。
+ * @note 该 API 仅用于请求隐藏键盘，不用于主动显示键盘。
  *
- * @app 1.2.3
+ * @app 4.4.0
  * @example
  * await mys.hideKeyboard()
  */
 export declare function hideKeyboard(params?: Callbacks): Promise<NativeResponse<void>>;
 /**
- * 监听键盘高度变化。
- *
- * 当当前 WebView 中的系统软键盘弹出、收起或高度变化时触发。
+ * 监听键盘高度变化，当前 WebView 中的系统软键盘弹出、收起或高度变化时触发。
  *
- * @note
- * 回调参数 height 单位为 CSS 逻辑像素，可直接用于页面布局。
- * 事件监听类型直接返回原始 payload，不包装 code/msg/result。
- * options.once 为 true 时只触发一次，触发后由 jsbridge 自动取消监听。
- *
- * @app 3.9.0
+ * @app 3.4.0
  * @example
  * mys.onKeyboardHeightChange((height) => {
  *   console.log('键盘高度:', height)
  * })
  *
+ * // 只监听一次
  * mys.onKeyboardHeightChange((height) => {
  *   console.log('只监听一次键盘高度:', height)
  * }, { once: true })
  *
+ * // 取消监听
  * mys.offKeyboardHeightChange()
  */
 export declare function onKeyboardHeightChange(callback: KeyboardHeightChangeCallback, options?: EventListenOptions): void;
 /**
  * 取消监听键盘高度变化。
  *
- * 不传 callback 时取消全部键盘高度监听；传入 callback 时只取消指定监听。
- *
- * @app 1.2.3
+ * @param callback 要取消的监听函数，不传则取消全部键盘高度监听
+ * @app 3.4.0
  * @example
  * mys.offKeyboardHeightChange()
  */
 export declare function offKeyboardHeightChange(callback?: KeyboardHeightChangeCallback): void;
 /**
- * 监听评论区面板状态变化。
- *
- * 当 Native 评论区面板打开、关闭或状态变化时触发。
- *
- * @note
- * 事件监听类型直接返回原始 payload，不包装 code/msg/result。
- * options.once 为 true 时只触发一次，触发后由 jsbridge 自动取消监听。
+ * 监听评论区面板状态变化，Native 评论区面板打开、关闭或状态变化时触发。
  *
  * @app 4.2.0
  * @example
@@ -102,18 +82,19 @@ export declare function offKeyboardHeightChange(callback?: KeyboardHeightChangeC
  *   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;
 /**
  * 取消监听评论区面板状态变化。
  *
- * 不传 callback 时取消全部评论区面板监听；传入 callback 时只取消指定监听。
- *
+ * @param callback 要取消的监听函数，不传则取消全部评论区面板监听
  * @app 4.2.0
  * @example
  * mys.offCommentPanelChange()
@@ -122,11 +103,10 @@ export declare function offCommentPanelChange(callback?: CommentPanelChangeCallb
 /**
  * 预览图片。
  *
- * @note
- * urls 不能为空。
- * current 为当前预览图片在 urls 中的数组下标，默认 0。
+ * @note current 超出 urls 范围时返回 1002。
+ * @note App 4.3.0 以下自动改用旧版预览，调用方式不变。
  *
- * @app 4.3.0
+ * @app 3.2.0
  * @example
  * await mys.previewImage({
  *   urls: ['https://example.com/1.jpg', 'mysFile://temp/files/xxx.jpg'],
@@ -135,12 +115,12 @@ export declare function offCommentPanelChange(callback?: CommentPanelChangeCallb
  */
 export declare function previewImage(params: PlayMediaParams): Promise<NativeResponse<void>>;
 /**
- * 预览视频。
+ * 预览视频，入参与 previewImage 相同，urls 为视频 URL 列表。
  *
- * @note
- * 视频预览与图片预览使用相同入参结构：urls 为视频 URL 列表，current 为当前播放视频的数组下标，默认 0。
+ * @note current 超出 urls 范围时返回 1002。
+ * @note App 4.3.0 以下自动改用旧版播放，一次只播放 current 对应的这一个视频。
  *
- * @app 1.2.3
+ * @app 3.2.0
  * @example
  * await mys.previewVideo({
  *   urls: ['https://example.com/video.mp4'],
@@ -151,10 +131,7 @@ export declare function previewVideo(params: PlayMediaParams): Promise<NativeRes
 /**
  * 选择或拍摄图片/视频。
  *
- * @note
- * 成功返回的 files[].tempFilePath 为临时文件路径，例如 mysFile://temp/xxxx.png。
- * tempFilePath 可用于 img / video 预览，也可传给 uploadFiles 上传。
- * 临时文件不应作为长期业务资源保存。
+ * @note 返回的是临时文件，不应作为长期业务资源保存。
  *
  * @app 4.3.0
  * @example
@@ -162,22 +139,18 @@ export declare function previewVideo(params: PlayMediaParams): Promise<NativeRes
  *   count: 1,
  *   mediaType: 'image',
  * })
- * console.log(res.result.files[0].tempFilePath)
+ * console.log(res.result.tempFiles[0].tempFilePath)
  */
 export declare function chooseMedia(params?: ChooseMediaParams): Promise<NativeResponse<ChooseMediaResult>>;
 /**
- * 上传本地临时文件。
- *
- * 批量串行上传 chooseMedia 返回的临时文件路径，成功后返回网络 URL。
+ * 批量串行上传本地临时文件（chooseMedia 返回的路径），成功后返回网络 URL。
  *
- * @note
- * filePath 应为 chooseMedia 返回的临时文件路径，例如 mysFiles://temp/xxxx.png。
- * cosDirPath 默认 multipleSource/common/。
+ * @note 同一时间只能有一个上传任务，上传过程中再次调用返回 1002。
  *
  * @app 4.3.0
  * @example
  * const uploadRes = await mys.uploadFiles({
- *   files: [chooseRes.result.files[0].tempFilePath],
+ *   files: [chooseRes.result.tempFiles[0].tempFilePath],
  * })
  * console.log(uploadRes.result.files[0].url)
  */
@@ -185,63 +158,74 @@ export declare function uploadFiles(params: UploadFilesParams): Promise<NativeRe
 /**
  * 保存图片到系统相册。
  *
- * @app 1.2.3
+ * @note filePath 只支持 base64（data URL 或纯 base64），网络地址和本地路径暂不支持，传入返回 1002。
+ * @note base64 整体经 Bridge 传给 Native，只适合 canvas 生成的分享图等小图，建议控制尺寸，没有透明需求时用 JPEG。
+ * @note 保存失败（无相册权限、数据无效等）时 Promise reject，errMsg 带 Native 返回的原因。
+ *
+ * @app 3.7.0
  * @example
- * await mys.saveImageToPhotosAlbum({ filePath: '/tmp/photo.jpg' })
+ * const canvas = await html2canvas(element)
+ * await mys.saveImageToPhotosAlbum({ filePath: canvas.toDataURL('image/png') })
  */
 export declare function saveImageToPhotosAlbum(params: SaveImageToPhotosAlbumParams): Promise<NativeResponse<void>>;
 /**
- * 保存视频到系统相册。
+ * 开始录音，录音结果通过 onEnd 回调返回。
+ *
+ * @note 首次录音会触发系统麦克风授权，被拒绝时返回 3002，可结合 checkPermission、openPhoneSetting 引导用户开启。
+ * @note 同一时间只能有一个录音，录音中再次调用返回 9101（RECORD_BUSY），需要先 cancelRecordAudio 再重试。
+ * @note 麦克风被占用、授权弹窗期间被取消、录音器初始化失败等其他启动失败统一返回 9102（RECORD_FAILED），原因见 errMsg。
+ * @note onEnd、onProgress 不需要手动取消，启动失败、stopRecordAudio 失败、调用 cancelRecordAudio、录音结束或再次调用 startRecordAudio 时自动取消。
+ * @note 被来电等系统事件打断时，已录制的部分保留并通过 onEnd 返回，是否使用由业务决定。
  *
- * @app 1.2.3
+ * @app 4.4.0
  * @example
- * await mys.saveVideoToPhotosAlbum({ filePath: '/tmp/video.mp4' })
+ * await mys.startRecordAudio({
+ *   maxDuration: 60,
+ *   onProgress: ({ decibel }) => console.log('当前音量:', decibel),
+ *   onEnd: (res) => console.log(res.tempFilePath, res.duration, res.size, res.fileType),
+ * })
  */
-export declare function saveVideoToPhotosAlbum(params: SaveVideoToPhotosAlbumParams): Promise<NativeResponse<void>>;
+export declare function startRecordAudio(params?: StartRecordAudioParams): Promise<NativeResponse<void>>;
 /**
- * 开始录音。
+ * 停止录音并保留录音文件，文件信息通过 startRecordAudio 的 onEnd 回调返回。
  *
- * @note
- * maxDuration 表示录音最大时长，具体默认值由宿主 App 决定。
+ * @note 当前没有录音时也返回成功。
+ * @note 调用失败说明这次录音没有产出结果，onEnd、onProgress 随之取消。
  *
- * @app 1.2.3
+ * @app 4.4.0
  * @example
- * await mys.startRecord({ maxDuration: 60 })
+ * await mys.stopRecordAudio()
  */
-export declare function startRecord(params?: StartRecordParams): Promise<NativeResponse<void>>;
+export declare function stopRecordAudio(params?: Callbacks): Promise<NativeResponse<void>>;
 /**
- * 停止录音。
+ * 取消录音并丢弃录音文件。
  *
- * @app 1.2.3
+ * @note 取消不会触发 onEnd，调用后 onEnd、onProgress 立即取消。
+ * @note 当前没有录音时也返回成功。
+ *
+ * @app 4.4.0
  * @example
- * await mys.stopRecord()
+ * await mys.cancelRecordAudio()
  */
-export declare function stopRecord(params?: Callbacks): Promise<NativeResponse<void>>;
+export declare function cancelRecordAudio(params?: Callbacks): Promise<NativeResponse<void>>;
 /**
  * 获取系统信息。
  *
- * @app 1.2.3
+ * @note 返回字段以 UA 的 webBaseInfo 为准，原样保留 snake_case。
+ * @note 4.4.0 及以上调用 Native 的 getSystemInfo，再用 H5 侧能拿到的 pixelRatio、screenWidth、screenHeight、windowWidth、windowHeight 补齐，同名字段以 Native 返回为准。
+ * @note 低于 4.4.0 的 App 没有该 Native 方法，改为从 UA 本地合成，不经过 Native。
+ * @note UA 里缺失的字段（如旧版没有的 env、webviewType、jsNum）为空，读取时按需判空。
+ *
+ * @app 4.4.0
  * @example
  * const res = await mys.getSystemInfo()
- * console.log(res.result.platform)
+ * console.log(res.result.app_version, res.result.network_type)
  */
 export declare function getSystemInfo(params?: Callbacks<SystemInfoResult>): Promise<NativeResponse<SystemInfoResult>>;
-/**
- * 获取当前网络类型。
- *
- * @app 1.2.3
- * @example
- * const res = await mys.getNetworkType()
- * console.log(res.result.networkType)
- */
-export declare function getNetworkType(params?: Callbacks<NetworkTypeResult>): Promise<NativeResponse<NetworkTypeResult>>;
 /**
  * 设置系统剪贴板的内容。
  *
- * @note
- * data 可以为空字符串，但不能为 undefined。
- *
- * @app 1.2.3
+ * @app 4.4.0
  * @example
  * await mys.setClipboardData({ data: 'hello world' })
  */
@@ -249,53 +233,166 @@ export declare function setClipboardData(params: SetClipboardDataParams): Promis
 /**
  * 获取系统剪贴板的内容。
  *
- * @app 1.2.3
+ * @app 4.4.0
  * @example
  * const res = await mys.getClipboardData()
  * console.log(res.result.data)
  */
 export declare function getClipboardData(params?: Callbacks<GetClipboardDataResult>): Promise<NativeResponse<GetClipboardDataResult>>;
 /**
- * 检查应用权限。
+ * 检查应用权限，返回权限类型 permission 和检查结果 result。
  *
- * @note
- * 返回权限类型 permission 和权限检查结果 result，可结合 openPhoneSetting 引导用户前往系统设置。
+ * @note 未授权时可结合 openPhoneSetting 引导用户前往系统设置。
+ * @note App 4.4.0 以下只能检查通知权限（permission 为 notification），且只能区分开启和关闭，关闭统一返回 denied，不会出现 permanentlyDenied。
+ * @note App 4.4.0 以下检查其余权限类型（相机、麦克风、定位、存储）返回 5002。
  *
- * @app 1.2.3
+ * @app 4.4.0
  * @example
  * const res = await mys.checkPermission({ permission: 'camera' })
  * if (res.result.result !== 'granted') {
- *   await mys.openPhoneSetting({ type: 'notice' })
+ *   await mys.openPhoneSetting({ permission: res.result.permission })
  * }
  */
 export declare function checkPermission(params: CheckPermissionParams): Promise<NativeResponse<CheckPermissionResult>>;
 /**
- * 打开系统通知设置页。
- *
- * 当前仅支持通知设置，用于引导用户前往系统设置中开启通知权限。
+ * 打开系统设置页，通常在 checkPermission 返回 denied 或 permanentlyDenied 后引导用户去开启。
  *
- * @note
- * 该 API 只负责请求宿主 App 打开对应系统设置页，不表示用户已经完成授权。
- * 返回成功仅表示已处理打开设置页的请求。
+ * @note 该 API 只负责请求宿主 App 打开对应系统设置页，不表示用户已经完成授权，可再调用 checkPermission 确认授权结果。
+ * @note App 4.4.0 以下只能打开通知设置页（permission 为 notification），其余类型低版本返回 5002。
  *
- * @app 1.2.3
+ * @app 4.4.0
  * @example
- * await mys.openPhoneSetting({ type: 'notice' })
+ * await mys.openPhoneSetting({ permission: 'notification' })
+ *
+ * const res = await mys.checkPermission({ permission: 'camera' })
+ * if (res.result.result !== 'granted') {
+ *   await mys.openPhoneSetting({ permission: res.result.permission })
+ * }
  */
 export declare function openPhoneSetting(params: OpenPhoneSettingParams): Promise<NativeResponse<void>>;
 /**
- * 关闭当前网页视图。
+ * 打开指定包名的其他 App（如游戏），未安装时触发下载。
+ *
+ * @note 不用于唤起本 App，本 App 的页面跳转使用 navigateTo 等。
+ * @note 已安装时直接打开，未安装时 Native 按 url 触发下载，H5 不需要自己跳转。
+ * @note result.type 为 1 表示未安装、已触发下载，可在此上报下载；为 2 表示已打开 App。
+ * @note 只在 App 内有效，浏览器里没有 Native 通道会失败，需要业务侧自行跳转下载地址。
  *
- * @app 1.2.3
+ * @app 3.2.0
  * @example
- * await mys.closeWebView()
+ * const res = await mys.openApp({
+ *   url: 'https://example.com/game.apk',
+ *   packageNames: ['com.example.game'],
+ * })
+ * if (res.result.type === 1) {
+ *   // 未安装，已触发下载
+ * }
+ */
+export declare function openApp(params?: OpenAppParams): Promise<NativeResponse<OpenAppResult>>;
+/**
+ * 启用或禁用当前页面的侧滑返回手势。
+ *
+ * @note Native 默认启用侧滑返回，只有需要拦截手势（如页面内有横向滑动操作）时才需要传 enable: false 禁用。
+ * @note enable 必须是布尔值，传其他类型返回 1002。
+ *
+ * @app 4.4.0
+ * @example
+ * await mys.swipeBack({ enable: false })
+ */
+export declare function swipeBack(params: SwipeBackParams): Promise<NativeResponse<void>>;
+/**
+ * 告知 Native 当前 H5 页面的类型，用于 Native 侧的页面识别和埋点。
+ *
+ * @app 3.3.0
+ * @example
+ * await mys.showPageName({ nameType: 1 })
+ */
+export declare function showPageName(params: ShowPageNameParams): Promise<NativeResponse<void>>;
+/**
+ * 通知 Native H5 页面已加载完成。
+ *
+ * @note 旧的 onPageLoaded 已弃用并从 SDK 移除，统一使用该方法。
+ *
+ * @app 3.2.0
+ * @example
+ * await mys.h5Loaded()
+ */
+export declare function h5Loaded(params?: Callbacks): Promise<NativeResponse<void>>;
+/**
+ * 获取上一个页面通过 setBeforeInfo 写入的埋点信息，用于埋点上报时拼接 BeforeInfo。
+ *
+ * @note 返回字段由 Native 决定，没有上一页信息时可能是空对象。
+ *
+ * @app 3.2.0
+ * @example
+ * const res = await mys.getBeforeInfo()
+ * console.log(res.result.PageID, res.result.PageName)
+ */
+export declare function getBeforeInfo(params?: Callbacks<BeforeInfoResult>): Promise<NativeResponse<BeforeInfoResult>>;
+/**
+ * 设置当前页面的埋点信息，跳转原生页面之前调用，供下一个页面通过 getBeforeInfo 读取并用于埋点上报。
+ *
+ * @app 3.2.0
+ * @example
+ * await mys.setBeforeInfo({ PageID: 10307, PageName: '积分商城页' })
+ */
+export declare function setBeforeInfo(params?: SetBeforeInfoParams): Promise<NativeResponse<void>>;
+/**
+ * 监听 H5 页面显示。
+ *
+ * @note Android 原生返回 H5 时用 visibilitychange 监听不到，Native 会通过该事件通知。
+ *
+ * @app 3.2.0
+ * @example
+ * mys.onPageShow(() => {
+ *   console.log('页面显示')
+ * })
+ */
+export declare function onPageShow(callback: PageEventCallback, options?: EventListenOptions): void;
+/**
+ * 取消监听 H5 页面显示。
+ *
+ * @param callback 要取消的监听函数，不传则取消全部页面显示监听
+ * @app 3.2.0
+ * @example
+ * mys.offPageShow()
+ */
+export declare function offPageShow(callback?: PageEventCallback): void;
+/**
+ * 监听 WebView 通知 H5 页面可见。
+ *
+ * @app 3.7.0
+ * @example
+ * mys.onPageVisible(() => {
+ *   console.log('页面可见')
+ * })
+ */
+export declare function onPageVisible(callback: PageEventCallback, options?: EventListenOptions): void;
+/**
+ * 取消监听 H5 页面可见。
+ *
+ * @param callback 要取消的监听函数，不传则取消全部页面可见监听
+ * @app 3.7.0
+ * @example
+ * mys.offPageVisible()
+ */
+export declare function offPageVisible(callback?: PageEventCallback): void;
+/**
+ * 监听 WebView 通知 H5 页面不可见。
+ *
+ * @app 3.7.0
+ * @example
+ * mys.onPageInvisible(() => {
+ *   console.log('页面不可见')
+ * })
  */
-export declare function closeWebView(params?: Callbacks): Promise<NativeResponse<void>>;
+export declare function onPageInvisible(callback: PageEventCallback, options?: EventListenOptions): void;
 /**
- * 使用外部浏览器打开链接。
+ * 取消监听 H5 页面不可见。
  *
- * @app 1.2.3
+ * @param callback 要取消的监听函数，不传则取消全部页面不可见监听
+ * @app 3.7.0
  * @example
- * await mys.openInExternalBrowser({ url: 'https://example.com' })
+ * mys.offPageInvisible()
  */
-export declare function openInExternalBrowser(params: OpenInExternalBrowserParams): Promise<NativeResponse<void>>;
+export declare function offPageInvisible(callback?: PageEventCallback): void;