npm - @kbapp/js-bridge - Versions diffs - 1.0.12-alpha.0 → 1.0.14-alpha.0 - Mend

@kbapp/js-bridge 1.0.12-alpha.0 → 1.0.14-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,1323 +1,108 @@
-# 开吧客户端桥接
-> ⚠️ 重要提示：本 SDK 基于 TypeScript 开发，所有 API 参数均带有明确的必填 / 选填类型标注。使用时请务必开启 TS 类型检查或在 IDE 中查看参数提示，必填项缺失会直接提示错误，选填项可按需传入，请勿忽略类型提示以避免使用异常。
-## 下载
-npm:
-```js
-npm i @kbapp/js-bridge
-```
-### 或通过 script 标签引入
-使用 unpkg CDN：
-```html
-<script src="https://unpkg.com/@kbapp/js-bridge@latest/dist/umd/index.js"></script>
-```
-使用 jsdelivr CDN：
-```html
-<script src="https://cdn.jsdelivr.net/npm/@kbapp/js-bridge@latest/dist/umd/index.js"></script>
-```
-> 通过 script 标签引入后，SDK 将作为全局变量 `kbBridge` 挂载在 window 对象上
-## 测试页面
-[https://unpkg.com/@kbapp/js-bridge@latest/examples/index.html](https://unpkg.com/@kbapp/js-bridge@latest/examples/index.html)
-## 示例
-```js
-import { saveImageToLocal } from '@kbapp/js-bridge'
-function saveImageHandle() {
-    saveImageToLocal({
-        imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
-        success() {
-            console.log('执行成功')
-        },
-    })
-}
-```
-### 通过 script 标签引入的使用示例
-```html
-<script src="https://unpkg.com/@kbapp/js-bridge@latest/dist/umd/index.js"></script>
-<script>
-async function saveImageHandle() {
-    // 通过全局变量kbBridge访问SDK功能
-    kbBridge.saveImageToLocal({
-        imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
-        success() {
-            console.log('保存成功')
-        },
-        fail(error) {
-            console.log('保存失败', error)
-        },
-    })
-}
-</script>
-```
-## 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`                  | 上报数据埋点              |
-| -         | `onLoopCheckAppLogin`            | 启动轮询检查 APP 登录状态 |
-| 31        | `getAppLoginInfo`                | 获取 app 登录信息         |
-| 31        | `triggerAppLogin`                | 触发 app 登录             |
-| 71        | `setScreenOrientation`           | 设置屏幕方向              |
-| 72        | `getAppSubscribeNotifyStatus`    | 获取APP订阅通知状态       |
-| 73        | `openAppSubscribeNotifySettings` | 前往/打开 app订阅管理页面 |
-| 1001      | `runAction`                      | 执行 action               |
-| 类/枚举         | 说明                  |
-| --------------- | --------------------- |
-| `BridgeCode`    | kbapp 桥接状态码      |
-| `IS_KB_APP_ENV` | 是否在开吧 APP 环境中 |
-| `AppLoginInfo`  | 登录信息模型          |
-| `AppShareModel` | 应用分享模型          |
-| `AppBaseInfo`   | 设备信息模型          |
-### checkForNewVersion
-> 检测是否有新版本可用, iOS 无论是否有最新版本都直接跳转到应用商店, 安卓如果有新版,则弹窗提示,没有的话 toast 提示无新版本
-#### 请求参数
-| 参数       | 类型                          | 必填 | 说明     |
-| ---------- | ----------------------------- | ---- | -------- |
-| `success`  | `() => void`                  | 否   | 成功回调 |
-| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调 |
-| `complete` | `() => void`                  | 否   | 完成回调 |
-#### 返回值
-```js
-Promise<void>
-```
-#### 示例代码
-```js
-import { checkForNewVersion } from '@kbapp/js-bridge'
-checkForNewVersion({
-    success() {
-        console.log('检查成功')
-    },
-    fail(error) {
-        console.log('检查失败', error)
-    },
-})
-```
-> 支持 Promise 风格调用
----
-### closeWebView
-> 关闭当前 webview
-#### 请求参数
-| 参数       | 类型                          | 必填 | 说明     |
-| ---------- | ----------------------------- | ---- | -------- |
-| `success`  | `() => void`                  | 否   | 成功回调 |
-| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调 |
-| `complete` | `() => void`                  | 否   | 完成回调 |
-#### 返回值
-```js
-Promise<void>
-```
-#### 示例代码
-```js
-import { closeWebView } from '@kbapp/js-bridge'
-closeWebView({
-    success() {
-        console.log('关闭成功')
-    },
-    fail(error) {
-        console.log('关闭失败', error)
-    },
-})
-```
-> 支持 Promise 风格调用
----
-### definePermissionUsage
-> 定义隐私权限协议文案
-#### 请求参数
-| 参数                     | 类型                          | 必填 | 说明           |
-| ------------------------ | ----------------------------- | ---- | -------------- |
-| `microphone`             | `object`                      | 否   | 麦克风权限说明 |
-| `microphone.description` | `string`                      | 是   | 麦克风权限描述 |
-| `camera`                 | `object`                      | 否   | 相机权限说明   |
-| `camera.description`     | `string`                      | 是   | 相机权限描述   |
-| `location`               | `object`                      | 否   | 位置权限说明   |
-| `location.description`   | `string`                      | 是   | 位置权限描述   |
-| `success`                | `() => void`                  | 否   | 成功回调       |
-| `fail`                   | `(error: BridgeCode) => void` | 否   | 失败回调       |
-| `complete`               | `() => void`                  | 否   | 完成回调       |
-#### 返回值
-```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
-| 参数         | 类型                          | 必填 | 说明                                         |
-| ------------ | ----------------------------- | ---- | -------------------------------------------- |
-| `onShareApp` | `() => AppShareModel`         | 是   | 点击分享时触发的函数，返回分享模型（方式 2） |
-| `success`    | `() => void`                  | 否   | 成功回调                                     |
-| `fail`       | `(error: BridgeCode) => void` | 否   | 失败回调                                     |
-| `complete`   | `() => void`                  | 否   | 完成回调                                     |
-#### 返回值
-```js
-Promise<void>
-```
-#### 示例代码
-```js
-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 风格调用
----
-### defineAppSharePanelState
-> 定义页面是否显示右上角分享菜单, 定义分享面板显示的相关状态
-#### 请求参数
-| 参数         | 类型                          | 必填 | 说明                                                                                          |
-| ------------ | ----------------------------- | ---- | --------------------------------------------------------------------------------------------- |
-| `showMenu`   | `boolean`                     | 是   | 是否显示右上角 ... 菜单                                                                       |
-| `panelStyle` | `0  1  2`                     | 否   | 显示分享面板布局, 0:正常显示. 1:只显示复制链接,浏览器打开相关. 2:只显示分享微信、QQ等. 默认 0 |
-| `success`    | `() => void`                  | 否   | 成功回调                                                                                      |
-| `fail`       | `(error: BridgeCode) => void` | 否   | 失败回调                                                                                      |
-| `complete`   | `() => void`                  | 否   | 完成回调                                                                                      |
-#### 返回值
-```js
-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
-import { generateKBSign } from '@kbapp/js-bridge'
-generateKBSign({
-    kbSignTime: Date.now(),
-    kbSignType: 1,
-    // 其他参数...
-    success(kbSign) {
-        console.log('签名结果', kbSign)
-    },
-    fail(error) {
-        console.log('签名失败', error)
-    },
-})
-```
-> 支持 Promise 风格调用
----
-### getAppLoginInfo
-> 获取 app 登录信息.如果未登录返回 null
-#### 请求参数
-| 参数       | 类型                          | 必填           | 说明     |
-| ---------- | ----------------------------- | -------------- | -------- | -------- |
-| `success`  | `(res: AppLoginInfo           | null) => void` | 否       | 成功回调 |
-| `fail`     | `(error: BridgeCode) => void` | 否             | 失败回调 |
-| `complete` | `() => void`                  | 否             | 完成回调 |
-#### 返回值
-```js
-Promise<AppLoginInfo | 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 风格调用
----
-### getAppBaseInfo
-> 获取设备信息
-#### 请求参数
-| 参数       | 类型                          | 必填 | 说明     |
-| ---------- | ----------------------------- | ---- | -------- |
-| `success`  | `(res: AppBaseInfo) => void`  | 否   | 成功回调 |
-| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调 |
-| `complete` | `() => void`                  | 否   | 完成回调 |
-#### 返回值
-```js
-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 风格调用
----
-### openAppSharePanel
-> 主动唤起分享面板
-#### 请求参数
-| 参数       | 类型                          | 必填 | 说明         |
-| ---------- | ----------------------------- | ---- | ------------ |
-| `title`    | `string`                      | 是   | 分享标题     |
-| `content`  | `string`                      | 否   | 分享内容     |
-| `imageUrl` | `string`                      | 是   | 分享图片 URL |
-| `url`      | `string`                      | 是   | 分享链接 URL |
-| `success`  | `() => void`                  | 否   | 成功回调     |
-| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调     |
-| `complete` | `() => void`                  | 否   | 完成回调     |
-#### 返回值
-```js
-Promise<void>
-```
-#### 示例代码
-```js
-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 风格调用
----
-### openPostEditor
-> 唤起发帖器
-#### 请求参数
-| 参数                          | 类型                              | 必填 | 说明                         |
-| ----------------------------- | --------------------------------- | ---- | ---------------------------- |
-| `postRule.hint`               | `string`                          | 否   | 文本输入框提示文案           |
-| `postRule.initialText`        | `string`                          | 否   | 初始化文本内容               |
-| `postRule.audio`              | `boolean`                         | 否   | 是否显示音频按钮，默认 true  |
-| `postRule.image`              | `boolean`                         | 否   | 是否显示图片按钮，默认 true  |
-| `postRule.video`              | `boolean`                         | 否   | 是否显示视频按钮，默认 true  |
-| `postRule.address`            | `boolean`                         | 否   | 是否显示定位按钮，默认 true  |
-| `postRule.asset_video`        | `boolean`                         | 否   | 是否显示媒资视频，默认 false |
-| `postRule.audio_must`         | `boolean`                         | 否   | 音频是否必传                 |
-| `postRule.image_must`         | `boolean`                         | 否   | 图片是否必传                 |
-| `postRule.max_image_count`    | `number`                          | 否   | 图片最大张数，默认 9         |
-| `postRule.min_image_count`    | `number`                          | 否   | 图片最小张数，默认 0         |
-| `postRule.video_must`         | `boolean`                         | 否   | 视频是否必传                 |
-| `postRule.text_must`          | `boolean`                         | 否   | 文本内容是否必传             |
-| `postRule.content_max_length` | `number`                          | 否   | 文本最大长度，默认 1000      |
-| `postRule.content_min_length` | `number`                          | 否   | 文本最小长度，默认 0         |
-| `success`                     | `(res: PostEditorResult) => void` | 否   | 成功回调                     |
-| `fail`                        | `(error: BridgeCode) => void`     | 否   | 失败回调                     |
-| `complete`                    | `() => void`                      | 否   | 完成回调                     |
-#### 返回值
-```js
-Promise<{
-    content: string
-    street?: string
-    audio?: unknown
-    video?: unknown
-    images?: { url: string; width: number; height: number }[]
-}>
-```
-#### 示例代码
-推荐使用 `generatePostEditorParamsByThreadPostRule` 构造参数
-```js
-import { generatePostEditorParamsByThreadPostRule, openPostEditor, KbRequirement } from '@kbapp/js-bridge'
-openPostEditor({
-    postRule: generatePostEditorParamsByThreadPostRule({
-        textMin: 0,
-        textMax: 1000,
-        /** 帖子中, 图片的最大张数 */
-        imageMax = 9,
-        /** 帖子中, 图片的最小张数 */
-        imageMin = 0,
-        /** 音频限制 */
-        audioRqr: KbRequirement.FREE,
-        /** 视频限制 */
-        videoRqr: KbRequirement.FREE,
-        /** 媒资限制 */
-        mediaRqr: KbRequirement.FORBID,
-        /** 位置-逆地理信息限制 */
-        streetRqr: KbRequirement.FREE
-    }),
-})
-openPostEditor({
-    postRule: {
-        hint: '请输入内容',
-        initialText: '默认内容',
-        image: true,
-        max_image_count: 9,
-    },
-    success(result) {
-        console.log('发帖内容', result)
-    },
-    fail(error) {
-        console.log('打开发帖器失败', error)
-    },
-})
-```
-> 支持 Promise 风格调用
----
-### onAppSharePanelShow
-> 监听分享面板打开时触发（主动和被动）
-#### 请求参数
-| 参数       | 类型        | 说明                 |
-| ---------- | ----------- | -------------------- |
-| `callback` | `()=> void` | 分享面板打开时的回调 |
-#### 返回值
-```js
-// 返回函数，调用该函数取消监听
-() => void
-```
-#### 示例代码
-```js
-import { onAppSharePanelShow } from '@kbapp/js-bridge'
-const stopHandle = onAppSharePanelShow(() => {
-    console.log('分享面板打开')
-})
-// stopHandle() 停止监听
-```
----
-### triggerAppLogin
-> 触发 app 登录
-#### 请求参数
-| 参数       | 类型                          | 必填 | 说明     |
-| ---------- | ----------------------------- | ---- | -------- |
-| `success`  | `() => void`                  | 否   | 成功回调 |
-| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调 |
-| `complete` | `() => void`                  | 否   | 完成回调 |
-#### 返回值
-```js
-Promise<void>
-```
-#### 示例代码
-```js
-import { triggerAppLogin, onLoopCheckAppLogin } from '@kbapp/js-bridge'
-// 监听登录成功
-const handle = onLoopCheckAppLogin((loginInfo) => {
-    console.log('登录成功', loginInfo)
-    handle() // 停止监听
-})
-// 触发登录
-triggerAppLogin({
-    success() {
-        console.log('触发登录成功')
-    },
-    fail(error) {
-        console.log('触发登录失败', error)
-    },
-})
-```
-> 支持 Promise 风格调用
----
-### onLoopCheckAppLogin
-> 启动轮询检查 APP 登录状态，查询到已登录后立即触发回调并自动回收回调函数（支持主动取消监听）
-#### 请求参数
-| 参数       | 类型                                | 说明         |
-| ---------- | ----------------------------------- | ------------ |
-| `callback` | `(loginInfo: AppLoginInfo) => void` | 登录成功回调 |
-#### 返回值
-```js
-// 返回函数,调用该函数,停止监听
-() => void
-```
-#### 示例代码
-```js
-import { onLoopCheckAppLogin } from '@kbapp/js-bridge'
-const handle = onLoopCheckAppLogin((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
-> app 执行 Action
-#### 请求参数
-| 参数           | 类型                          | 必填 | 说明         |
-| -------------- | ----------------------------- | ---- | ------------ |
-| `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 风格调用
----
-### saveImageToLocal
-> 保存图片到本地
-#### 请求参数
-| 参数       | 类型                          | 必填 | 说明         |
-| ---------- | ----------------------------- | ---- | ------------ |
-| `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 风格调用
----
-### saveVideoToLocal
-> 保存视频到本地
-#### 请求参数
-| 参数       | 类型                          | 必填 | 说明         |
-| ---------- | ----------------------------- | ---- | ------------ |
-| `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 风格调用
----
-### scanQRCode
-> 扫描二维码
-#### 请求参数
-| 参数       | 类型                          | 必填 | 说明                   |
-| ---------- | ----------------------------- | ---- | ---------------------- |
-| `success`  | `(res: string) => void`       | 否   | 成功回调，返回扫描结果 |
-| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调               |
-| `complete` | `() => void`                  | 否   | 完成回调               |
-#### 返回值
-```js
-Promise<string>
-```
-#### 示例代码
-```js
-import { scanQRCode } from '@kbapp/js-bridge'
-scanQRCode({
-    success(result) {
-        console.log('扫描结果', result)
-    },
-    fail(error) {
-        console.log('扫描失败', error)
-    },
-})
-```
-> 支持 Promise 风格调用
----
-### setScreenOrientation
-> 设置屏幕方向
-#### 请求参数
-| 参数          | 类型                          | 必填 | 说明                   |
-| ------------- | ----------------------------- | ---- | ---------------------- |
-| `orientation` | `number`                      | 是   | 屏幕方向 0:竖屏 1:横屏 |
-| `success`     | `() => void`                  | 否   | 成功回调               |
-| `fail`        | `(error: BridgeCode) => void` | 否   | 失败回调               |
-| `complete`    | `() => void`                  | 否   | 完成回调               |
-#### 返回值
-```js
-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 风格调用
----
-### setWebViewTitle
-> 设置网页标题(建议通过 document.title 设置)
-#### 请求参数
-| 参数       | 类型                          | 必填 | 说明             |
-| ---------- | ----------------------------- | ---- | ---------------- |
-| `title`    | `string`                      | 是   | webview 标题文案 |
-| `success`  | `() => void`                  | 否   | 成功回调         |
-| `fail`     | `(error: BridgeCode) => void` | 否   | 失败回调         |
-| `complete` | `() => void`                  | 否   | 完成回调         |
-#### 返回值
-```js
-Promise<void>
-```
-#### 异常返回值
-```js
-Promise<{ errCode: BridgeCode }>
-```
-#### 示例代码
-```js
-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
-Promise<void>
-```
-#### 异常返回值
-```js
-Promise<{ errCode: BridgeCode }>
-```
-#### 示例代码
-```js
-import { shareImage } from '@kbapp/js-bridge'
-shareImage({
-    imageUrl: 'https://example.com/poster.png',
-    success() {
-        console.log('分享海报成功')
-    },
-    fail(error) {
-        console.log('分享海报失败', error)
-    },
-})
-```
-> 支持 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 风格调用
----
-### 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 风格调用
-## 数据模型
-### AppLoginInfo
-> 登录信息模型
-```js
-class AppLoginInfo {
-    /** 车牌号:例如浙A999999 */
-    carNo?: string
-    /** 未知 */
-    role?: number
-    /** 手机号 */
-    mobile!: string
-    /** 性别 */
-    sex!: number
-    /** 电台id */
-    siteId!: number
-    /** 头像地址 */
-    avatar!: string
-    /** token */
-    token!: string
-    /** 用户id */
-    userId!: number
-    /** 用户名 */
-    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
-> 设备信息模型
-```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
-> 错误码枚举
-| 常量                                | 值   | 说明               |
-| ----------------------------------- | ---- | ------------------ |
-| `BridgeCode.UNKNOWN`                | 1000 | 未知错误           |
-| `BridgeCode.UNSUPPORTED_VERSION`    | 1001 | 当前开吧版本不支持 |
-| `BridgeCode.TIMEOUT`                | 1002 | 执行超时           |
-| `BridgeCode.UNSUPPORTED_BRIDGE_ENV` | 1003 | 请在开吧app内执行  |
-## 常见问题
-1. 桥接触发无反应: 请检查当前是否处于开吧 app 内,以及当前网页是否在白名单内
+# 开吧客户端桥接
+> ⚠️ 重要提示：本 SDK 基于 TypeScript 开发，所有 API 参数均带有明确的必填 / 选填类型标注。使用时请务必开启 TS 类型检查或在 IDE 中查看参数提示，必填项缺失会直接提示错误，选填项可按需传入，请勿忽略类型提示以避免使用异常。
+## 下载
+npm:
+```js
+npm i @kbapp/js-bridge
+```
+### 或通过 script 标签引入
+使用 unpkg CDN：
+```html
+<script src="https://unpkg.com/@kbapp/js-bridge@latest/dist/umd/index.js"></script>
+```
+使用 jsdelivr CDN：
+```html
+<script src="https://cdn.jsdelivr.net/npm/@kbapp/js-bridge@latest/dist/umd/index.js"></script>
+```
+> 通过 script 标签引入后，SDK 将作为全局变量 `kbBridge` 挂载在 window 对象上
+## 测试页面
+[https://unpkg.com/@kbapp/js-bridge@latest/examples/index.html](https://unpkg.com/@kbapp/js-bridge@latest/examples/index.html)
+## 示例
+```js
+import { saveImageToLocal } from '@kbapp/js-bridge'
+function saveImageHandle() {
+    saveImageToLocal({
+        imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
+        success() {
+            console.log('执行成功')
+        },
+    })
+}
+```
+### 通过 script 标签引入的使用示例
+```html
+<script src="https://unpkg.com/@kbapp/js-bridge@latest/dist/umd/index.js"></script>
+<script>
+async function saveImageHandle() {
+    // 通过全局变量kbBridge访问SDK功能
+    kbBridge.saveImageToLocal({
+        imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
+        success() {
+            console.log('保存成功')
+        },
+        fail(error) {
+            console.log('保存失败', error)
+        },
+    })
+}
+</script>
+```
+## API
+### 总览
+| 桥接 type | 方法 | 说明 | 链接 |
+| --------- | ---- | ---- | ---- |
+| - | `defineBridgeCallback` | 定义桥接调用的回调函数 | [查看文档](docs/api/define-bridge-callback.md) |
+| - | `runBridgeApi` | 执行桥接(无返回值) | [查看文档](docs/api/run-bridge-api.md) |
+| - | `runBridgeApiResponse` | 执行桥接(等待响应) | [查看文档](docs/api/run-bridge-api-response.md) |
+| - | `isAppVersionSupport` | 判断当前版本号是否支持 | [查看文档](docs/api/is-app-version-support.md) |
+| -1 | `closeWebView` | 关闭当前 webview | [查看文档](docs/api/close-web-view.md) |
+| - | `definePermissionUsage` | 定义隐私权限协议文案 | [查看文档](docs/api/define-permission-usage.md) |
+| - | `onAppSharePanelShow` | 监听分享面板打开事件 | [查看文档](docs/api/on-app-share-panel-show.md) |
+| 12 | `defineAppShareModel` | 定义页面分享内容 | [查看文档](docs/api/define-app-share-model.md) |
+| 58 | `openAppSharePanel` | 主动唤起分享面板 | [查看文档](docs/api/open-app-share-panel.md) |
+| 68 | `defineAppSharePanelState` | 定义分享面板控件布局 | [查看文档](docs/api/define-app-share-panel-state.md) |
+| 13 | `openPostEditor` | 唤起发帖器 | [查看文档](docs/api/open-post-editor.md) |
+| 26 | `scanQRCode` | 扫描二维码 | [查看文档](docs/api/scan-qrcode.md) |
+| 35 | `getAppBaseInfo` | 获取设备信息 | [查看文档](docs/api/get-app-base-info.md) |
+| 51 | `generateKBSign` | 生成 kbsign | [查看文档](docs/api/generate-kbsign.md) |
+| 56 | `checkForNewVersion` | 检测是否有新版本 | [查看文档](docs/api/check-for-new-version.md) |
+| 58 | `shareImage` | 分享海报 | [查看文档](docs/api/share-image.md) |
+| 64 | `setWebViewTitle` | 设置网页标题 | [查看文档](docs/api/set-web-view-title.md) |
+| 62 | `saveImageToLocal` | 保存图片到本地 | [查看文档](docs/api/save-image-to-local.md) |
+| 63 | `saveVideoToLocal` | 保存视频到本地 | [查看文档](docs/api/save-video-to-local.md) |
+| 69 | `reportDAEvent` | 上报数据埋点 | [查看文档](docs/api/report-daevent.md) |
+| - | `onLoopCheckAppLogin` | 启动轮询检查 APP 登录状态 | [查看文档](docs/api/on-loop-check-app-login.md) |
+| 31 | `getAppLoginInfo` | 获取 app 登录信息 | [查看文档](docs/api/get-app-login-info.md) |
+| 31 | `triggerAppLogin` | 触发 app 登录 | [查看文档](docs/api/trigger-app-login.md) |
+| 71 | `setScreenOrientation` | 设置屏幕方向 | [查看文档](docs/api/set-screen-orientation.md) |
+| 72 | `getAppSubscribeNotifyStatus` | 获取APP订阅通知状态 | [查看文档](docs/api/get-app-subscribe-notify-status.md) |
+| 73 | `openAppSubscribeNotifySettings` | 前往/打开 app订阅管理页面 | [查看文档](docs/api/open-app-subscribe-notify-settings.md) |
+| 1001 | `runAction` | 执行 action | [查看文档](docs/api/run-action.md) |
+| 类/枚举         | 说明                  |
+| --------------- | --------------------- |
+| `BridgeCode`    | kbapp 桥接状态码      |
+| `IS_KB_APP_ENV` | 是否在开吧 APP 环境中 |
+| `AppLoginInfo`  | 登录信息模型          |
+| `AppShareModel` | 应用分享模型          |
+| `AppBaseInfo`   | 设备信息模型          |