@kbapp/js-bridge 0.4.8-alpha.0 → 1.0.0-alpha.0

package/README.MD

@@ -1,6 +1,6 @@
 # 开吧客户端桥接
 
-> 该桥接仅限于开吧 app 内使用
+> ⚠️ 重要提示：本 SDK 基于 TypeScript 开发，所有 API 参数均带有明确的必填 / 选填类型标注。使用时请务必开启 TS 类型检查或在 IDE 中查看参数提示，必填项缺失会直接提示错误，选填项可按需传入，请勿忽略类型提示以避免使用异常。
 
 ## 下载
 
@@ -10,111 +10,248 @@ npm:
 npm i @kbapp/js-bridge
 ```
 
-yarn:
+### 或通过 script 标签引入
+
+使用 unpkg CDN：
+
+```html
+<script src="https://unpkg.com/@kbapp/js-bridge@latest/dist/index.umd.js"></script>
+```
+
+使用 jsdelivr CDN：
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@kbapp/js-bridge@latest/dist/index.umd.js"></script>
+```
+
+> 通过 script 标签引入后，SDK 将作为全局变量 `kbBridge` 挂载在 window 对象上
+
+## 示例
 
 ```js
-yarn add @kbapp/js-bridge
+import { saveImageToLocal, BridgeCode } from '@kbapp/js-bridge'
+
+function saveImageHandle() {
+    saveImageToLocal({
+        imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
+        success() {
+            console.log('执行成功')
+        },
+    })
+}
 ```
 
-pnpm:
+### 通过 script 标签引入的使用示例
 
 ```js
-pnpm add @kbapp/js-bridge
+// 通过全局变量kbBridge访问SDK功能
+async function saveImageHandle() {
+    kbBridge.saveImageToLocal({
+        imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
+        success() {
+            console.log('保存成功')
+        },
+        fail(error) {
+            console.log('保存失败', error)
+        },
+    })
+}
 ```
 
-## 示例
+## 测试页面
+
+> 可以通过以下地址访问 SDK 的测试页面，查看所有 API 的使用示例
+
+测试页面地址：
+
+```
+https://unpkg.com/@kbapp/js-bridge@latest/examples/index.html
+```
+
+## API
+
+### 总览
+
+| 桥接 type | 方法                             | 说明                      |
+| --------- | -------------------------------- | ------------------------- |
+| -         | `defineBridgeCallback`           | 定义桥接调用的回调函数    |
+| -         | `runBridgeApi`                   | 执行桥接(无返回值)        |
+| -         | `runBridgeApiResponse`           | 执行桥接(等待响应)        |
+| -         | `isAppVersionSupport`            | 判断当前版本号是否支持    |
+| -1        | `closeWebView`                   | 关闭当前 webview          |
+| -         | `onAppSharePanelShow`            | 监听分享面板打开事件      |
+| 12        | `defineAppShareModel`            | 定义页面分享内容          |
+| 58        | `openAppSharePanel`              | 主动唤起分享面板          |
+| 68        | `defineAppSharePanelState`       | 定义分享面板控件布局      |
+| 13        | `openPostEditor`                 | 唤起发帖器                |
+| 26        | `scanQRCode`                     | 扫描二维码                |
+| 35        | `getAppBaseInfo`                 | 获取设备信息              |
+| 51        | `generateKBSign`                 | 生成 kbsign               |
+| 56        | `checkForNewVersion`             | 检测是否有新版本          |
+| 58        | `shareImage`                     | 分享海报                  |
+| 64        | `setWebViewTitle`                | 设置网页标题              |
+| 62        | `saveImageToLocal`               | 保存图片到本地            |
+| 63        | `saveVideoToLocal`               | 保存视频到本地            |
+| 69        | `reportDAEvent`                  | 上报数据埋点              |
+| -         | `onAppLoginSuccess`              | 监听登录成功回调          |
+| 31        | `getAppLoginInfo`                | 获取 app 登录信息         |
+| 31        | `triggerAppLogin`                | 触发 app 登录             |
+| 71        | `setScreenOrientation`           | 设置屏幕方向              |
+| 72        | `getAppSubscribeNotifyStatus`    | 获取APP订阅通知状态       |
+| 73        | `openAppSubscribeNotifySettings` | 前往/打开 app订阅管理页面 |
+| 1001      | `runAction`                      | 执行 action               |
+
+| 类/枚举              | 说明             |
+| -------------------- | ---------------- |
+| `BridgeCode`         | kbapp 桥接状态码 |
+| `AppBridgedUserInfo` | 登录信息模型     |
+| `AppShareModel`      | 应用分享模型     |
+| `AppBaseInfo`        | 设备信息模型     |
+
+### checkForNewVersion
+
+> 检测是否有新版本可用, iOS 无论是否有最新版本都直接跳转到应用商店, 安卓如果有新版,则弹窗提示,没有的话 toast 提示无新版本
+
+#### 请求参数
+
+| 参数       | 类型                          | 必填 | 说明     |
+| ---------- | ----------------------------- | ---- | -------- |
+| `success`  | `() => void`                  | 否   | 成功回调 |
+| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调 |
+| `complete` | `() => void`                  | 否   | 完成回调 |
+
+#### 返回值
 
 ```js
-import { saveImageToLocal, JSBridgeCode } from '@kbapp/js-bridge'
-
-defineComponents({
-    /** 保存图片案例 */
-    async saveImageHandle() {
-        try {
-            await saveImageToLocal({
-                imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
-            })
-        } catch (error) {
-            switch (error.errCode) {
-                case JSBridgeCode.UNSUPPORTED_VERSION:
-                    // 用户当前版本为支持该桥接,此时应当引导用户升级app
-                    // 用户同意后,可以调用 checkForNewVersion()或者前往应用商城
-                    return
-
-                default:
-                    return
-            }
-        }
+Promise<void>
+```
+
+#### 示例代码
+
+```js
+import { checkForNewVersion } from '@kbapp/js-bridge'
+
+checkForNewVersion({
+    success() {
+        console.log('检查成功')
+    },
+    fail(error) {
+        console.log('检查失败', error)
     },
 })
 ```
 
-## Api
+> 支持 Promise 风格
 
-### 总览
+---
+
+### closeWebView
+
+> 关闭当前 webview
+
+#### 请求参数
+
+| 参数       | 类型                          | 必填 | 说明     |
+| ---------- | ----------------------------- | ---- | -------- |
+| `success`  | `() => void`                  | 否   | 成功回调 |
+| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调 |
+| `complete` | `() => void`                  | 否   | 完成回调 |
+
+#### 返回值
+
+```js
+Promise<void>
+```
+
+#### 示例代码
 
-| 方法                  | 说明                           |
-| --------------------- | ------------------------------ |
-| checkForNewVersion    | 检测是否有新版本               |
-| closeWebView          | 关闭当前 webview               |
-| definePermissionUsage | 定义隐私权限协议文案           |
-| getDeviceInfo         | 获取设备信息                   |
-| openPostEditor        | 唤起发帖器                     |
-| runAction             | 执行 action                    |
-| saveImageToLocal      | 保存图片到本地                 |
-| saveVideoToLocal      | 保存视频到本地                 |
-| setWebViewTitle       | 设置网页标题                   |
-| defineShareModel      | 设置当前页面分享时显示卡片样式 |
-| defineShareModelState | 定义分享面板控件布局           |
-| invokeShareModal      | 主动唤起更多分享模态框         |
-| sharePoster           | 分享海报                       |
-| getAppLoginInfo       | 获取 app 登录信息              |
-| triggerAppLogin       | 触发 app 登录                  |
-| watchAppLoginSuccess  | 监听登录成功回调               |
-| reportGetui           | 个推事件上报                   |
-| generateKBSign        | 生成 kbsign                    |
-
-| 枚举               | 说明             |
-| ------------------ | ---------------- |
-| JSBridgeCode       | kbapp 桥接状态码 |
-| AppBridgedUserInfo | 登录信息 model   |
-
-### 登录设计
-
-以小程序运行逻辑参考
-
-#### 如果是点击某个按钮再执行登录的情况
-
-提供装饰器, 注入回调函数
-
-```js
-const onTapSomeButton = decorateLogin(() => {
-    // Todo someting
+```js
+import { closeWebView } from '@kbapp/js-bridge'
+
+closeWebView({
+    success() {
+        console.log('关闭成功')
+    },
+    fail(error) {
+        console.log('关闭失败', error)
+    },
 })
 ```
 
-该装饰器执行逻辑为如果未登录, 则执行登录操作(比如跳转到登录页面), 并直接抛出异常, 不做 _监听登录成功后执行回调函数_ 操作
+> 支持 Promise 风格
 
-> 那岂不是用户登陆完成后回到当页面还需与再点一下
+---
 
-没错, 的确要这么设计, 原因是为了解 如果点击了 2 个通过装饰器包装的按钮, 登陆成功后, 2 个按钮的回调事件将会全部执行(其实也有办法解决, 只是多点代码) 这种情况, 测试较真的话, 真是个问题
-担心一个动作触发累计多个回调事件, 导致逻辑混乱
+### definePermissionUsage
 
-#### 如果是某个组件/页面加载的时候就得登录才能正常操作
+> 定义隐私权限协议文案
 
-暂时没想好, 反正也是需要禁止无限制事件类型, 小程序情况下, 某个链接点击打开小程序, 然后关闭, 再重新点链接打开小程序, 页面生命周期是重复触发 onMounted
+#### 请求参数
 
-其中最终的目的就是禁止出现监听登录成功事件无限累加, 曾经在这上面吃了不少的亏
+| 参数                     | 类型                          | 必填 | 说明           |
+| ------------------------ | ----------------------------- | ---- | -------------- |
+| `microphone`             | `object`                      | 否   | 麦克风权限说明 |
+| `microphone.description` | `string`                      | 是   | 麦克风权限描述 |
+| `camera`                 | `object`                      | 否   | 相机权限说明   |
+| `camera.description`     | `string`                      | 是   | 相机权限描述   |
+| `location`               | `object`                      | 否   | 位置权限说明   |
+| `location.description`   | `string`                      | 是   | 位置权限描述   |
+| `success`                | `() => void`                  | 否   | 成功回调       |
+| `fail`                   | `(error: BridgeCode) => void` | 否   | 失败回调       |
+| `complete`               | `() => void`                  | 否   | 完成回调       |
 
-### saveImageToLocal
+#### 返回值
 
-> 保存图片到本地
+```js
+Promise<void>
+```
 
-#### 请求参数
+#### 示例代码
+
+```js
+import { definePermissionUsage } from '@kbapp/js-bridge'
+
+definePermissionUsage({
+    microphone: { description: '用于发帖上传音频' },
+    location: { description: '获取你选择的位置信息，用于线下导航服务' },
+    camera: { description: '收集你选中的照片或视频信息，用于发表评论、分享视频' },
+    success() {
+        console.log('设置成功')
+    },
+    fail(error) {
+        console.log('设置失败', error)
+    },
+})
+```
+
+> 支持 Promise 风格
+
+---
+
+### defineAppShareModel
+
+> 定义 app 点击转发时候的分享卡片内容
+
+#### 请求参数 方式 1
+
+| 参数       | 类型                          | 必填 | 说明         |
+| ---------- | ----------------------------- | ---- | ------------ |
+| `title`    | `string`                      | 是   | 分享标题     |
+| `content`  | `string`                      | 否   | 分享内容     |
+| `imageUrl` | `string`                      | 是   | 分享图片 URL |
+| `url`      | `string`                      | 是   | 分享链接 URL |
+| `success`  | `() => void`                  | 否   | 成功回调     |
+| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调     |
+| `complete` | `() => void`                  | 否   | 完成回调     |
+
+#### 请求参数 方式 2
 
-| 参数     | 值类型 | 说明         |
-| -------- | ------ | ------------ |
-| imageUrl | string | 图片网络地址 |
+| 参数         | 类型                          | 必填 | 说明                                         |
+| ------------ | ----------------------------- | ---- | -------------------------------------------- |
+| `onShareApp` | `() => AppShareModel`         | 是   | 点击分享时触发的函数，返回分享模型（方式 2） |
+| `success`    | `() => void`                  | 否   | 成功回调                                     |
+| `fail`       | `(error: BridgeCode) => void` | 否   | 失败回调                                     |
+| `complete`   | `() => void`                  | 否   | 完成回调                                     |
 
 #### 返回值
 
@@ -122,23 +259,62 @@ const onTapSomeButton = decorateLogin(() => {
 Promise<void>
 ```
 
-#### 异常返回值
+#### 示例代码
 
 ```js
-Promise<{ errCode: JSBridgeCode }>
+import { defineAppShareModel } from '@kbapp/js-bridge'
+
+// 方式1：直接提供分享模型
+defineAppShareModel({
+    title: '分享标题',
+    content: '分享内容',
+    imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
+    url: 'http://www.kaiba315.com.cn/',
+    success() {
+        console.log('设置成功')
+    },
+    fail(error) {
+        console.log('设置失败', error)
+    },
+})
+
+// 方式2：提供分享模型函数（点击分享时动态生成分享内容）
+defineAppShareModel({
+    onShareApp() {
+        // 点击页面右上角或分享按钮时触发该回调，动态生成分享内容
+        return {
+            title: '动态生成的分享标题',
+            content: '动态生成的分享内容',
+            imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
+            url: 'http://www.kaiba315.com.cn/?t=' + Date.now(),
+        }
+    },
+    success() {
+        console.log('设置成功')
+    },
+    fail(error) {
+        console.log('设置失败', error)
+    },
+})
 ```
 
+> 支持 Promise 风格
+
 ---
 
-### saveVideoToLocal
+### defineAppSharePanelState
 
-> 保存视频到本地
+> 定义页面是否显示右上角分享菜单, 定义分享面板显示的相关状态
 
 #### 请求参数
 
-| 参数     | 值类型 | 必填? | 说明         |
-| -------- | ------ | ----- | ------------ |
-| videoUrl | string | 必填  | 视频网络地址 |
+| 参数         | 类型                          | 必填 | 说明                                                                                          |
+| ------------ | ----------------------------- | ---- | --------------------------------------------------------------------------------------------- |
+| `showMenu`   | `boolean`                     | 是   | 是否显示右上角 ... 菜单                                                                       |
+| `panelStyle` | `0  1  2`                     | 否   | 显示分享面板布局, 0:正常显示. 1:只显示复制链接,浏览器打开相关. 2:只显示分享微信、QQ等. 默认 0 |
+| `success`    | `() => void`                  | 否   | 成功回调                                                                                      |
+| `fail`       | `(error: BridgeCode) => void` | 否   | 失败回调                                                                                      |
+| `complete`   | `() => void`                  | 否   | 完成回调                                                                                      |
 
 #### 返回值
 
@@ -146,48 +322,164 @@ Promise<{ errCode: JSBridgeCode }>
 Promise<void>
 ```
 
-#### 异常返回值
+#### 示例代码
+
+```js
+import { defineAppSharePanelState } from '@kbapp/js-bridge'
+
+defineAppSharePanelState({
+    showMenu: true,
+    panelStyle: 0,
+    success() {
+        console.log('设置成功')
+    },
+    fail(error) {
+        console.log('设置失败', error)
+    },
+})
+```
+
+> 支持 Promise 风格
+
+---
+
+### generateKBSign
+
+> 生成 kbsign
+
+#### 请求参数
+
+| 参数         | 类型                          | 必填 | 说明                   |
+| ------------ | ----------------------------- | ---- | ---------------------- |
+| `kbSignTime` | `number`                      | 是   | 签名时间戳             |
+| `kbSignType` | `number`                      | 是   | 签名类型               |
+| `...`        | `any`                         | 否   | 其他需要签名的参数     |
+| `success`    | `(res: string) => void`       | 否   | 成功回调，返回签名结果 |
+| `fail`       | `(error: BridgeCode) => void` | 否   | 失败回调               |
+| `complete`   | `() => void`                  | 否   | 完成回调               |
+
+#### 返回值
+
+```js
+Promise<string>
+```
+
+#### 示例代码
 
 ```js
-Promise<{ errCode: JSBridgeCode }>
+import { generateKBSign } from '@kbapp/js-bridge'
+
+generateKBSign({
+    kbSignTime: Date.now(),
+    kbSignType: 1,
+    // 其他参数...
+    success(kbSign) {
+        console.log('签名结果', kbSign)
+    },
+    fail(error) {
+        console.log('签名失败', error)
+    },
+})
 ```
 
+> 支持 Promise 风格
+
 ---
 
-### defineShareModelState
+### getAppLoginInfo
+
+> 获取 app 登录信息.如果未登录返回 null
+
+#### 请求参数
+
+| 参数       | 类型                          | 必填           | 说明     |
+| ---------- | ----------------------------- | -------------- | -------- | -------- |
+| `success`  | `(res: AppBridgedUserInfo     | null) => void` | 否       | 成功回调 |
+| `fail`     | `(error: BridgeCode) => void` | 否             | 失败回调 |
+| `complete` | `() => void`                  | 否             | 完成回调 |
+
+#### 返回值
+
+```js
+Promise<AppBridgedUserInfo | null>
+```
+
+#### 示例代码
+
+```js
+import { getAppLoginInfo } from '@kbapp/js-bridge'
+
+getAppLoginInfo({
+    success(loginInfo) {
+        if (loginInfo) {
+            console.log('已登录', loginInfo)
+        } else {
+            console.log('未登录')
+        }
+    },
+    fail(error) {
+        console.log('获取登录信息失败', error)
+    },
+})
+```
+
+> 支持 Promise 风格
 
 ---
 
-### invokeShareModal
+### getAppBaseInfo
 
-> 唤起分享更多模态框
+> 获取设备信息
 
 #### 请求参数
 
-| 参数     | 值类型 | 必填? | 说明               |
-| -------- | ------ | ----- | ------------------ |
-| title    | string | 必填  | 分享的标题         |
-| content  | string | 必填  | 分享的内容(副标题) |
-| url      | string | 必填  | 分享的网页链接     |
-| imageUrl | string | 必填  | 分享的图片         |
+| 参数       | 类型                          | 必填 | 说明     |
+| ---------- | ----------------------------- | ---- | -------- |
+| `success`  | `(res: AppBaseInfo) => void`  | 否   | 成功回调 |
+| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调 |
+| `complete` | `() => void`                  | 否   | 完成回调 |
 
 #### 返回值
 
 ```js
-void
+Promise<AppBaseInfo>
+```
+
+#### 示例代码
+
+```js
+import { getAppBaseInfo } from '@kbapp/js-bridge'
+
+getAppBaseInfo({
+    success(deviceInfo) {
+        console.log('设备信息', deviceInfo)
+        console.log('版本号', deviceInfo.vcode)
+    },
+    fail(error) {
+        console.log('获取设备信息失败', error)
+    },
+})
 ```
 
+> 支持 Promise 风格
+
 ---
 
-### sharePoster
+### openAppSharePanel
 
-> 分享图片
+> 主动唤起分享面板
 
 #### 请求参数
 
-| 参数     | 值类型 | 必填? | 说明                                  |
-| -------- | ------ | ----- | ------------------------------------- |
-| imageUrl | string | 必填  | 分享的图片链接,仅支持网络地址,png/jpg |
+| 参数       | 类型                          | 必填 | 说明         |
+| ---------- | ----------------------------- | ---- | ------------ |
+| `title`    | `string`                      | 是   | 分享标题     |
+| `content`  | `string`                      | 否   | 分享内容     |
+| `imageUrl` | `string`                      | 是   | 分享图片 URL |
+| `url`      | `string`                      | 是   | 分享链接 URL |
+| `success`  | `() => void`                  | 否   | 成功回调     |
+| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调     |
+| `complete` | `() => void`                  | 否   | 完成回调     |
 
 #### 返回值
 
@@ -195,80 +487,193 @@ void
 Promise<void>
 ```
 
-#### 异常返回值
+#### 示例代码
 
 ```js
-Promise<{ errCode: JSBridgeCode }>
+import { openAppSharePanel } from '@kbapp/js-bridge'
+
+openAppSharePanel({
+    title: '开吧分享',
+    content: '开吧，开汽车上新生活！',
+    url: 'http://www.kaiba315.com.cn/',
+    imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
+    success() {
+        console.log('打开分享面板成功')
+    },
+    fail(error) {
+        console.log('打开分享面板失败', error)
+    },
+})
 ```
 
+> 支持 Promise 风格
+
 ---
 
-### setWebViewTitle
+### openPostEditor
 
-> 设置网页标题(建议通过 document.title 设置)
+> 唤起发帖器
 
 #### 请求参数
 
-| 参数  | 值类型 | 必填? | 说明             |
-| ----- | ------ | ----- | ---------------- |
-| title | string | 必填  | webview 标题文案 |
+| 参数                 | 类型                              | 必填 | 说明                         |
+| -------------------- | --------------------------------- | ---- | ---------------------------- |
+| `hint`               | `string`                          | 否   | 文本输入框提示文案           |
+| `initialText`        | `string`                          | 否   | 初始化文本内容               |
+| `audio`              | `boolean`                         | 否   | 是否显示音频按钮，默认 true  |
+| `image`              | `boolean`                         | 否   | 是否显示图片按钮，默认 true  |
+| `video`              | `boolean`                         | 否   | 是否显示视频按钮，默认 true  |
+| `address`            | `boolean`                         | 否   | 是否显示定位按钮，默认 true  |
+| `asset_video`        | `boolean`                         | 否   | 是否显示媒资视频，默认 false |
+| `audio_must`         | `boolean`                         | 否   | 音频是否必传                 |
+| `image_must`         | `boolean`                         | 否   | 图片是否必传                 |
+| `max_image_count`    | `number`                          | 否   | 图片最大张数，默认 9         |
+| `min_image_count`    | `number`                          | 否   | 图片最小张数，默认 0         |
+| `video_must`         | `boolean`                         | 否   | 视频是否必传                 |
+| `text_must`          | `boolean`                         | 否   | 文本内容是否必传             |
+| `content_max_length` | `number`                          | 否   | 文本最大长度，默认 1000      |
+| `content_min_length` | `number`                          | 否   | 文本最小长度，默认 0         |
+| `success`            | `(res: PostEditorResult) => void` | 否   | 成功回调                     |
+| `fail`               | `(error: BridgeCode) => void`     | 否   | 失败回调                     |
+| `complete`           | `() => void`                      | 否   | 完成回调                     |
 
 #### 返回值
 
 ```js
-Promise<void>
+Promise<{
+    content: string
+    street?: string
+    audio?: unknown
+    video?: unknown
+    images?: { url: string; width: number; height: number }[]
+}>
 ```
 
-#### 异常返回值
+#### 示例代码
 
 ```js
-Promise<{ errCode: JSBridgeCode }>
+import { openPostEditor } from '@kbapp/js-bridge'
+
+openPostEditor({
+    hint: '请输入内容',
+    initialText: '默认内容',
+    image: true,
+    max_image_count: 9,
+    success(result) {
+        console.log('发帖内容', result)
+    },
+    fail(error) {
+        console.log('打开发帖器失败', error)
+    },
+})
 ```
 
+> 支持 Promise 风格
+
 ---
 
-### checkForNewVersion
+### onAppSharePanelShow
 
-> 检测是否有新版本可用, iOS 无论是否有最新版本都直接跳转到应用商店, 安卓如果有新版,则弹窗提示,没有的话 toast 提示无新版本
+> 监听分享面板打开时触发（主动和被动）
 
 #### 请求参数
 
-无
+| 参数       | 类型        | 说明                 |
+| ---------- | ----------- | -------------------- |
+| `callback` | `()=> void` | 分享面板打开时的回调 |
 
 #### 返回值
 
 ```js
-void
+// 返回函数，调用该函数取消监听
+() => void
+```
+
+#### 示例代码
+
+```js
+import { onAppSharePanelShow } from '@kbapp/js-bridge'
+
+const stopHandle = onAppSharePanelShow(() => {
+    console.log('分享面板打开')
+})
+
+// stopHandle() 停止监听
 ```
 
 ---
 
-### canIUse
+### onAppLoginSuccess
 
-> 检测某个方法能被当前版本使用
+> 登录完成会触发回调函数,调用该时将会立刻检测当前是否登录
 
 #### 请求参数
 
-传入方法名(string)
+| 参数       | 类型                                      | 说明         |
+| ---------- | ----------------------------------------- | ------------ |
+| `callback` | `(loginInfo: AppBridgedUserInfo) => void` | 登录成功回调 |
 
 #### 返回值
 
 ```js
-Promise<boolean>
+// 返回函数,调用该函数,停止监听
+() => void
 ```
 
-#### 示例
+#### 示例代码
 
 ```js
-import { canIUse } from '@kbapp/js-bridge'
+import { onAppLoginSuccess } from '@kbapp/js-bridge'
 
-if (await canIUse('sharePoster')) {
-    console.log('当前app版本能使用')
-} else {
-    console.log('请升级app')
-}
+const handle = onAppLoginSuccess((loginInfo) => {
+    console.log('登录成功', loginInfo)
+})
+
+// handle() 停止监听
+```
+
+---
+
+### reportDAEvent
+
+> 上报数据埋点
+
+#### 请求参数
+
+| 参数          | 类型                          | 必填 | 说明             |
+| ------------- | ----------------------------- | ---- | ---------------- |
+| `eventName`   | `string`                      | 是   | 事件名           |
+| `eventParams` | `object`                      | 否   | 上报参数         |
+| `eventType`   | `string`                      | 否   | 开始结束类型传递 |
+| `success`     | `() => void`                  | 否   | 成功回调         |
+| `fail`        | `(error: BridgeCode) => void` | 否   | 失败回调         |
+| `complete`    | `() => void`                  | 否   | 完成回调         |
+
+#### 返回值
+
+```js
+Promise<void>
+```
+
+#### 示例代码
+
+```js
+import { reportDAEvent } from '@kbapp/js-bridge'
+
+reportDAEvent({
+    eventName: 'page_view',
+    eventParams: { page: 'home' },
+    success() {
+        console.log('上报数据成功')
+    },
+    fail(error) {
+        console.log('上报数据失败', error)
+    },
+})
 ```
 
+> 支持 Promise 风格
+
 ---
 
 ### runAction
@@ -277,157 +682,615 @@ if (await canIUse('sharePoster')) {
 
 #### 请求参数
 
-| 参数         | 值类型 | 必填? | 说明         |
-| ------------ | ------ | ----- | ------------ |
-| action       | string | 必填  | action       |
-| actionParams | string | 选填  | actionParams |
+| 参数           | 类型                          | 必填 | 说明         |
+| -------------- | ----------------------------- | ---- | ------------ |
+| `action`       | `string`                      | 是   | action       |
+| `actionParams` | `object`                      | 否   | actionParams |
+| `success`      | `() => void`                  | 否   | 成功回调     |
+| `fail`         | `(error: BridgeCode) => void` | 否   | 失败回调     |
+| `complete`     | `() => void`                  | 否   | 完成回调     |
 
 #### 返回值
 
-无
+```js
+Promise<void>
+```
+
+#### 示例代码
+
+```js
+import { runAction } from '@kbapp/js-bridge'
+
+runAction({
+    action: 'pageWeb',
+    actionParams: {
+        url: 'https://www.baidu.com',
+    },
+    success() {
+        console.log('执行成功')
+    },
+    fail(error) {
+        console.log('执行失败', error)
+    },
+})
+```
+
+> 支持 Promise 风格
 
 ---
 
-### closeWebView
+### saveImageToLocal
 
-> 关闭当前 webview
+> 保存图片到本地
 
 #### 请求参数
 
-无
+| 参数       | 类型                          | 必填 | 说明         |
+| ---------- | ----------------------------- | ---- | ------------ |
+| `imageUrl` | `string`                      | 是   | 图片网络地址 |
+| `success`  | `() => void`                  | 否   | 成功回调     |
+| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调     |
+| `complete` | `() => void`                  | 否   | 完成回调     |
 
 #### 返回值
 
-无
+```js
+Promise<void>
+```
+
+#### 异常返回值
+
+```js
+Promise<{ errCode: BridgeCode }>
+```
+
+#### 示例代码
+
+```js
+import { saveImageToLocal, BridgeCode } from '@kbapp/js-bridge'
+
+saveImageToLocal({
+    imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
+    success() {
+        console.log('保存图片成功')
+    },
+    fail(error) {
+        console.log('保存图片失败', error)
+    },
+})
+```
+
+> 支持 Promise 风格
 
 ---
 
-### defineShareModel
+### saveVideoToLocal
 
-> 定义当前页面分享文案
+> 保存视频到本地
 
 #### 请求参数
 
-| 参数     | 值类型 | 必填? | 说明       |
-| -------- | ------ | ----- | ---------- |
-| title    | string | 必填  | 标题       |
-| content  | string | 选填  | 内容       |
-| imageUrl | string | 必填  | 图片       |
-| url      | string | 必填  | https 链接 |
-| tmuTrack | any    | 选填  | 天目埋点   |
-| qqUrl    | string | 选填  | 未知       |
+| 参数       | 类型                          | 必填 | 说明         |
+| ---------- | ----------------------------- | ---- | ------------ |
+| `videoUrl` | `string`                      | 是   | 视频网络地址 |
+| `success`  | `() => void`                  | 否   | 成功回调     |
+| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调     |
+| `complete` | `() => void`                  | 否   | 完成回调     |
 
 #### 返回值
 
-无
+```js
+Promise<void>
+```
+
+#### 异常返回值
+
+```js
+Promise<{ errCode: BridgeCode }>
+```
+
+#### 示例代码
+
+```js
+import { saveVideoToLocal } from '@kbapp/js-bridge'
+
+saveVideoToLocal({
+    videoUrl: 'https://example.com/video.mp4',
+    success() {
+        console.log('保存视频成功')
+    },
+    fail(error) {
+        console.log('保存视频失败', error)
+    },
+})
+```
+
+> 支持 Promise 风格
 
 ---
 
-### getAppLoginInfo
+### scanQRCode
 
-> 获取 app 登录信息.如果未登录返回 null
+> 扫描二维码
 
 #### 请求参数
 
-无
+| 参数       | 类型                          | 必填 | 说明                   |
+| ---------- | ----------------------------- | ---- | ---------------------- |
+| `success`  | `(res: string) => void`       | 否   | 成功回调，返回扫描结果 |
+| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调               |
+| `complete` | `() => void`                  | 否   | 完成回调               |
 
 #### 返回值
 
 ```js
-Promise<AppBridgedUserInfo | null>
+Promise<string>
+```
+
+#### 示例代码
 
+```js
+import { scanQRCode } from '@kbapp/js-bridge'
+
+scanQRCode({
+    success(result) {
+        console.log('扫描结果', result)
+    },
+    fail(error) {
+        console.log('扫描失败', error)
+    },
+})
 ```
 
+> 支持 Promise 风格
+
 ---
 
-### triggerAppLogin
+### setScreenOrientation
 
-> 唤起 app 登录. 如果已登录,将直接返回登录信息
+> 设置屏幕方向
 
 #### 请求参数
 
-无
+| 参数          | 类型                          | 必填 | 说明                   |
+| ------------- | ----------------------------- | ---- | ---------------------- |
+| `orientation` | `number`                      | 是   | 屏幕方向 0:竖屏 1:横屏 |
+| `success`     | `() => void`                  | 否   | 成功回调               |
+| `fail`        | `(error: BridgeCode) => void` | 否   | 失败回调               |
+| `complete`    | `() => void`                  | 否   | 完成回调               |
 
 #### 返回值
 
 ```js
-Promise<AppBridgedUserInfo>
+Promise<void>
+```
+
+#### 示例代码
+
+```js
+import { setScreenOrientation } from '@kbapp/js-bridge'
+
+// 设置为横屏
+setScreenOrientation({
+    orientation: 1,
+    success() {
+        console.log('设置横屏成功')
+    },
+    fail(error) {
+        console.log('设置横屏失败', error)
+    },
+})
 
+// 设置为竖屏
+setScreenOrientation({
+    orientation: 0,
+    success() {
+        console.log('设置竖屏成功')
+    },
+    fail(error) {
+        console.log('设置竖屏失败', error)
+    },
+})
 ```
 
+> 支持 Promise 风格
+
 ---
 
-### watchAppLoginSuccess
+### setWebViewTitle
 
-> 登录完成会触发回调函数,调用该时将会立刻检测当前是否登录
+> 设置网页标题(建议通过 document.title 设置)
 
 #### 请求参数
 
+| 参数       | 类型                          | 必填 | 说明             |
+| ---------- | ----------------------------- | ---- | ---------------- |
+| `title`    | `string`                      | 是   | webview 标题文案 |
+| `success`  | `() => void`                  | 否   | 成功回调         |
+| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调         |
+| `complete` | `() => void`                  | 否   | 完成回调         |
+
+#### 返回值
+
+```js
+Promise<void>
+```
+
+#### 异常返回值
+
+```js
+Promise<{ errCode: BridgeCode }>
+```
+
+#### 示例代码
+
 ```js
-(loginInfo) => void
+import { setWebViewTitle } from '@kbapp/js-bridge'
+
+setWebViewTitle({
+    title: '页面标题',
+    success() {
+        console.log('设置标题成功')
+    },
+    fail(error) {
+        console.log('设置标题失败', error)
+    },
+})
 ```
 
+> 支持 Promise 风格
+
+---
+
+### shareImage
+
+> 分享海报
+
+#### 请求参数
+
+| 参数       | 类型                          | 必填 | 说明                                  |
+| ---------- | ----------------------------- | ---- | ------------------------------------- |
+| `imageUrl` | `string`                      | 是   | 分享的图片链接,仅支持网络地址,png/jpg |
+| `success`  | `() => void`                  | 否   | 成功回调                              |
+| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调                              |
+| `complete` | `() => void`                  | 否   | 完成回调                              |
+
 #### 返回值
 
 ```js
-// 返回函数,调用该函数,停止监听
-() => void
+Promise<void>
+```
+
+#### 异常返回值
+
+```js
+Promise<{ errCode: BridgeCode }>
 ```
 
 #### 示例代码
 
 ```js
-import { watchAppLoginSuccess } from '@kbapp/js-bridge'
+import { shareImage } from '@kbapp/js-bridge'
 
-const handle = watchAppLoginSuccess(() => {
-    console.log('登录成功')
+shareImage({
+    imageUrl: 'https://example.com/poster.png',
+    success() {
+        console.log('分享海报成功')
+    },
+    fail(error) {
+        console.log('分享海报失败', error)
+    },
 })
+```
 
-// handle() 停止监听
+> 支持 Promise 风格
+
+---
+
+### subscribeNotify
+
+> 订阅通知
+
+#### 请求参数
+
+| 参数       | 类型                          | 必填 | 说明     |
+| ---------- | ----------------------------- | ---- | -------- |
+| `bizType`  | `number`                      | 是   | 业务类型 |
+| `subState` | `number`                      | 是   | 订阅状态 |
+| `success`  | `() => void`                  | 否   | 成功回调 |
+| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调 |
+| `complete` | `() => void`                  | 否   | 完成回调 |
+
+#### 返回值
+
+```js
+Promise<void>
+```
+
+#### 示例代码
+
+```js
+import { subscribeNotify } from '@kbapp/js-bridge'
+
+subscribeNotify({
+    bizType: 1,
+    subState: 1,
+    success() {
+        console.log('订阅通知成功')
+    },
+    fail(error) {
+        console.log('订阅通知失败', error)
+    },
+})
+```
+
+> 支持 Promise 风格
+
+---
+
+### triggerAppLogin
+
+> 触发 app 登录
+
+#### 请求参数
+
+| 参数       | 类型                          | 必填 | 说明     |
+| ---------- | ----------------------------- | ---- | -------- |
+| `success`  | `() => void`                  | 否   | 成功回调 |
+| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调 |
+| `complete` | `() => void`                  | 否   | 完成回调 |
+
+#### 返回值
+
+```js
+Promise<void>
 ```
 
+#### 示例代码
+
+```js
+import { triggerAppLogin, onAppLoginSuccess } from '@kbapp/js-bridge'
+
+// 监听登录成功
+const handle = onAppLoginSuccess((loginInfo) => {
+    console.log('登录成功', loginInfo)
+    handle() // 停止监听
+})
+
+// 触发登录
+triggerAppLogin({
+    success() {
+        console.log('触发登录成功')
+    },
+    fail(error) {
+        console.log('触发登录失败', error)
+    },
+})
+```
+
+> 支持 Promise 风格
+
 ---
 
+### isAppVersionSupport
+
+> 判断当前版本号是否支持
+
+#### 请求参数
+
+| 参数         | 类型                          | 必填 | 说明                   |
+| ------------ | ----------------------------- | ---- | ---------------------- |
+| `minVersion` | `number`                      | 是   | 最低支持版本号         |
+| `success`    | `(res: boolean) => void`      | 否   | 成功回调，返回是否支持 |
+| `fail`       | `(error: BridgeCode) => void` | 否   | 失败回调               |
+| `complete`   | `() => void`                  | 否   | 完成回调               |
+
+#### 返回值
+
+```js
+Promise<boolean>
+```
+
+#### 示例代码
+
+```js
+import { isAppVersionSupport } from '@kbapp/js-bridge'
+
+isAppVersionSupport({
+    minVersion: 80711,
+    success(result) {
+        console.log('是否能使用', result)
+    },
+    fail(error) {
+        console.log('检查版本支持失败', error)
+    },
+})
+```
+
+> 支持 Promise 风格
+
+## 数据模型
+
 ### AppBridgedUserInfo
 
-> 登录信息类型
+> 登录信息模型
 
 ```js
-Promise<{
+class AppBridgedUserInfo {
     /** 车牌号:例如浙A999999 */
     carNo?: string
+
     /** 未知 */
     role?: number
+
     /** 手机号 */
-    mobile: string
+    mobile!: string
+
     /** 性别 */
-    sex: number
+    sex!: number
+
     /** 电台id */
-    siteId: number
+    siteId!: number
+
     /** 头像地址 */
-    avatar: string
+    avatar!: string
+
     /** token */
-    token: string
+    token!: string
+
     /** 用户id */
-    userId: number
+    userId!: number
+
     /** 用户名 */
-    userName: string
-}>
+    userName?: string
+}
+```
+
+### AppShareModel
+
+> 应用分享模型
 
+```js
+class AppShareModel {
+    /**
+     * 标题
+     */
+    title!: string
+
+    /**
+     * 文字内容
+     */
+    content?: string
+
+    /**
+     * 图片
+     */
+    imageUrl!: string
+
+    /**
+     * 分享链接
+     */
+    url!: string
+
+    /**
+     * 分享功能是否开启. 默认为 true.
+     * 当分享功能关闭时, 其他分享相关字段均无效.
+     */
+    enabled?: boolean
+
+    /**
+     * 海报分享标题.
+     * 客户端: 海报分享必须. 若不存在则取 {@link #title}, 若也不存在, 则海报分享功能关闭.
+     * H5: 非必填. 通过桥接给到客户端时, 建议可以只填充 {@link #title}.
+     * 后端: 非必填.
+     */
+    posterTitle?: string
+
+    /**
+     * 海报分享内容.
+     * 客户端: 非必须. 若不存在则取 {@link #content}, 若也不存在, 则海报只有标题内容.
+     * H5: 非必填. 通过桥接给到客户端时, 建议可以只填充 {@link #content}.
+     * 后端: 非必填.
+     */
+    posterContent?: string
+
+    /**
+     * 海报分享封面图.
+     * 客户端: 海报分享非必须. 若不存在则取 {@link #imageUrl}, 若也不存在, 则海报无封面.
+     * H5: 非必填. 通过桥接给到客户端时, 建议可以只填充 {@link #imageUrl}.
+     * 后端: 非必填.
+     */
+    posterUrl?: string
+
+    /**
+     * 海报分享的展示时间.
+     * 客户端: 海报分享非必须. 若不存在则海报不展示时间.
+     * H5: 非必填. 通过桥接给到客户端时, 建议忽略该字段.
+     * 后端: 非必填.
+     */
+    posterTime?: string
+
+    /** 海报分享展示时间格式. */
+    posterTimeFormat?: string
+
+    /**
+     * 海报分享功能是否开启. 默认为 false.
+     * 当海报分享功能关闭时, 其他海报分享相关字段均无效.
+     */
+    posterEnabled?: boolean
+
+    /**
+     * 分享小程序设置: 小程序原始ID.
+     * 获取方法: 登录小程序管理后台-设置-基本设置-帐号信息.
+     *
+     * 当此字段非空时, 客户端会显示 '分享至小程序' 功能.
+     */
+    wxMiniUserName?: string
+
+    /**
+     * 分享小程序设置: 小程序页面路径.
+     */
+    wxMiniPath?: string
+
+    /**
+     * 分享小程序设置: 额外信息.
+     * 通常开发者希望分享出去的小程序被二次打开时可以获取到更多信息, 例如群的标识.
+     */
+    wxMiniShareTicket?: boolean
+
+    /**
+     * 分享小程序设置: 小程序的类型.
+     * 0为正式版, 1为测试版, 2为体验版.
+     */
+    wxMiniType?: number
+}
 ```
 
----
+### AppBaseInfo
 
-### JSBridgeCode
+> 设备信息模型
 
-> 错误码枚举
+```js
+interface AppBaseInfo {
+    /** 操作系统，例如 iOS */
+    do: string
+
+    /** 设备型号，例如 iPhone11,2 */
+    db: string
+
+    /** 系统版本，例如 15.5 */
+    dv: string
 
-#### 键值对
+    /** 应用版本号（数字），例如 69011 */
+    vcode: number
+
+    /** 应用版本号（字符串），例如 6.90.11 */
+    v: string
+
+    /** 未知 */
+    source: number
+
+    /** 电台 id */
+    siteId: number
+
+    /** 用户 id，当登录时返回 */
+    userId?: number
+
+    /** 未知 */
+    cid: string
+}
+```
+
+## BridgeCode
+
+> 错误码枚举
 
-| key                 | value | 说明                                                   |
-| ------------------- | ----- | ------------------------------------------------------ |
-| UNSUPPORTED_VERSION | 1001  | 用户当前 app 版本不支持该 桥接(此时请引导用户升级 app) |
-| UN_LOGIN            | 1002  | APP 未登录                                             |
+| 常量                                | 值   | 说明               |
+| ----------------------------------- | ---- | ------------------ |
+| `BridgeCode.UNKNOWN`                | 1000 | 未知错误           |
+| `BridgeCode.UNSUPPORTED_VERSION`    | 1001 | 当前开吧版本不支持 |
+| `BridgeCode.TIMEOUT`                | 1002 | 执行超时           |
+| `BridgeCode.UNSUPPORTED_BRIDGE_ENV` | 1003 | 请在开吧app内执行  |
 
 ## 常见问题