开吧客户端桥接

该桥接仅限于开吧 app 内使用

下载

npm:

npm i @kbapp/js-bridge

yarn:

yarn add @kbapp/js-bridge

pnpm:

pnpm add @kbapp/js-bridge

示例

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
            }
        }
    },
})

Api

总览

| 方法 | 说明 | | --------------------- | ------------------------------ | | 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 |

登录设计

以小程序运行逻辑参考

如果是点击某个按钮再执行登录的情况

提供装饰器, 注入回调函数

const onTapSomeButton = decorateLogin(() => {
    // Todo someting
})

该装饰器执行逻辑为如果未登录, 则执行登录操作(比如跳转到登录页面), 并直接抛出异常, 不做 监听登录成功后执行回调函数 操作

那岂不是用户登陆完成后回到当页面还需与再点一下

没错, 的确要这么设计, 原因是为了解 如果点击了 2 个通过装饰器包装的按钮, 登陆成功后, 2 个按钮的回调事件将会全部执行(其实也有办法解决, 只是多点代码) 这种情况, 测试较真的话, 真是个问题 担心一个动作触发累计多个回调事件, 导致逻辑混乱

如果是某个组件/页面加载的时候就得登录才能正常操作

暂时没想好, 反正也是需要禁止无限制事件类型, 小程序情况下, 某个链接点击打开小程序, 然后关闭, 再重新点链接打开小程序, 页面生命周期是重复触发 onMounted

其中最终的目的就是禁止出现监听登录成功事件无限累加, 曾经在这上面吃了不少的亏

saveImageToLocal

保存图片到本地

请求参数

| 参数 | 值类型 | 说明 | | -------- | ------ | ------------ | | imageUrl | string | 图片网络地址 |

返回值

Promise<void>

异常返回值

Promise<{ errCode: JSBridgeCode }>

saveVideoToLocal

保存视频到本地

请求参数

| 参数 | 值类型 | 必填? | 说明 | | -------- | ------ | ----- | ------------ | | videoUrl | string | 必填 | 视频网络地址 |

返回值

Promise<void>

异常返回值

Promise<{ errCode: JSBridgeCode }>

defineShareModelState

invokeShareModal

唤起分享更多模态框

请求参数

| 参数 | 值类型 | 必填? | 说明 | | -------- | ------ | ----- | ------------------ | | title | string | 必填 | 分享的标题 | | content | string | 必填 | 分享的内容(副标题) | | url | string | 必填 | 分享的网页链接 | | imageUrl | string | 必填 | 分享的图片 |

返回值

void

sharePoster

分享图片

请求参数

| 参数 | 值类型 | 必填? | 说明 | | -------- | ------ | ----- | ------------------------------------- | | imageUrl | string | 必填 | 分享的图片链接,仅支持网络地址,png/jpg |

返回值

Promise<void>

异常返回值

Promise<{ errCode: JSBridgeCode }>

setWebViewTitle

设置网页标题(建议通过 document.title 设置)

请求参数

| 参数 | 值类型 | 必填? | 说明 | | ----- | ------ | ----- | ---------------- | | title | string | 必填 | webview 标题文案 |

返回值

Promise<void>

异常返回值

Promise<{ errCode: JSBridgeCode }>

checkForNewVersion

检测是否有新版本可用, iOS 无论是否有最新版本都直接跳转到应用商店, 安卓如果有新版,则弹窗提示,没有的话 toast 提示无新版本

请求参数

无

返回值

void

canIUse

检测某个方法能被当前版本使用

请求参数

传入方法名(string)

返回值

Promise<boolean>

示例

import { canIUse } from '@kbapp/js-bridge'

if (await canIUse('sharePoster')) {
    console.log('当前app版本能使用')
} else {
    console.log('请升级app')
}

runAction

app 执行 Action

请求参数

| 参数 | 值类型 | 必填? | 说明 | | ------------ | ------ | ----- | ------------ | | action | string | 必填 | action | | actionParams | string | 选填 | actionParams |

返回值

无

closeWebView

关闭当前 webview

请求参数

无

返回值

无

defineShareModel

定义当前页面分享文案

请求参数

| 参数 | 值类型 | 必填? | 说明 | | -------- | ------ | ----- | ---------- | | title | string | 必填 | 标题 | | content | string | 选填 | 内容 | | imageUrl | string | 必填 | 图片 | | url | string | 必填 | https 链接 | | tmuTrack | any | 选填 | 天目埋点 | | qqUrl | string | 选填 | 未知 |

返回值

无

getAppLoginInfo

获取 app 登录信息.如果未登录返回 null

请求参数

无

返回值

Promise<AppBridgedUserInfo | null>

triggerAppLogin

唤起 app 登录. 如果已登录,将直接返回登录信息

请求参数

无

返回值

Promise<AppBridgedUserInfo>

watchAppLoginSuccess

登录完成会触发回调函数,调用该时将会立刻检测当前是否登录

请求参数

(loginInfo) => void

返回值

// 返回函数,调用该函数,停止监听
() => void

示例代码

import { watchAppLoginSuccess } from '@kbapp/js-bridge'

const handle = watchAppLoginSuccess(() => {
    console.log('登录成功')
})

// handle() 停止监听

AppBridgedUserInfo

登录信息类型

Promise<{
    /** 车牌号:例如浙A999999 */
    carNo?: string
    /** 未知 */
    role?: number
    /** 手机号 */
    mobile: string
    /** 性别 */
    sex: number
    /** 电台id */
    siteId: number
    /** 头像地址 */
    avatar: string
    /** token */
    token: string
    /** 用户id */
    userId: number
    /** 用户名 */
    userName: string
}>

JSBridgeCode

错误码枚举

键值对

| key | value | 说明 | | ------------------- | ----- | ------------------------------------------------------ | | UNSUPPORTED_VERSION | 1001 | 用户当前 app 版本不支持该 桥接(此时请引导用户升级 app) | | UN_LOGIN | 1002 | APP 未登录 |

常见问题

1. 桥接触发无反应: 请检查当前是否处于开吧 app 内,以及当前网页是否在白名单内