@wenext/bridge

WeNext H5 与 Native 通信桥接库，提供统一的 TypeScript API。

安装

pnpm add @wenext/bridge

App 配置

通过构建时环境变量 VUE_APP_APP 自动识别当前 App，无需手动初始化。

支持的 App：lama、wyak、misu、lama-ludo、weparty、inchat、hichat、yoki、fungo、hayi

// 直接使用，自动根据 VUE_APP_APP 返回对应值
import { getSchemeHost, getAppName, getWebHost } from '@wenext/bridge'

getSchemeHost() // 'courage://ludo'（当 VUE_APP_APP=lama-ludo）
getAppName()    // 'Lama Ludo'
getWebHost()    // 根据 NODE_ENV 自动区分 dev/prod 域名

使用方式

所有 API 统一从 @wenext/bridge 主入口导入：

import {
  // 设备
  getDeviceInfo, getVersionCode, getOs,
  // 用户
  getMyUserInfo, getToken, getMyUid, getLanguageCode,
  // 导航
  closeWindow, openFullPageWebView, goUserProfile, goRoom, dispatchDeeplink,
  // Native 消息监听
  addNativeMessageListener, removeNativeMessageListener,
  // 广播
  webBroadcast, listen,
  // 常量
  MSG_TYPE, CODE,
} from '@wenext/bridge'

也可以按模块引入：

import { device, user, navigation, share } from '@wenext/bridge'

const deviceInfo = await device.getDeviceInfo()
const userInfo = await user.getMyUserInfo()
navigation.closeWindow()
share.goShare({ shareText: 'Hello', deeplink: '...' })

Native 消息监听

import { MSG_TYPE, addNativeMessageListener, removeNativeMessageListener } from '@wenext/bridge'

addNativeMessageListener(MSG_TYPE.ON_RESUME, (data) => {
  console.log('onResume', data)
})

removeNativeMessageListener(MSG_TYPE.ON_RESUME)

广播通信

import { webBroadcast, listen } from '@wenext/bridge'

webBroadcast('gameAction', { action: 'start' })

const unListen = listen('gameAction', (message) => {
  console.log('收到消息:', message)
})
unListen()

API 模块一览

模块	说明
device	getDeviceInfo, getVersionCode, getOs, getStatusBarHeight, getSafeAreaInfo...
user	getMyUserInfo, getToken, getMyUid, getLanguageCode, getCountryCode...
navigation	closeWindow, openFullPageWebView, goUserProfile, goRoom, dispatchDeeplink...
payment	launchGooglePay, launchApplePay, showRechargeTip...
share	goShare, shareLink, copyToClipBoard...
media	playSound, stopSound...
storage	KVStorageGet, KVStorageSet
game	callNativeGameMethod, listenCallGameMethod...
broadcast	webBroadcast, listen
misc	log, stat, reportAfBackEvent, request...

从 @mono/bridge 迁移

// ❌ 旧写法
import { callNativeMethodAsync } from '@mono/bridge/base'
import { MSG_TYPE } from '@mono/bridge/constant'
import { getSchemeHost } from '@mono/bridge'

// ✅ 新写法 - 统一从主入口导入
import { callNativeMethodAsync, MSG_TYPE, getSchemeHost } from '@wenext/bridge'

不再支持子路径导入（如 @wenext/bridge/base），所有 API 统一从主入口导出。

添加新方法

1. 添加类型定义（如果需要）

在 src/core/types.ts 中添加接口：

/**
 * 你的参数类型
 */
export interface YourParams {
  key: string
  value: number
}

2. 在对应模块中添加方法

选择合适的模块文件：

• 设备相关 → src/api/device.ts
• 用户相关 → src/api/user.ts
• 导航相关 → src/api/navigation.ts
• 支付相关 → src/api/payment.ts
• 分享相关 → src/api/share.ts
• 媒体相关 → src/api/media.ts
• 存储相关 → src/api/storage.ts
• 游戏相关 → src/api/game.ts
• 广播相关 → src/api/broadcast.ts
• 其他功能 → src/api/misc.ts

在文件中添加：

// 1. 导入类型（如果有新类型）
import type { YourParams } from '../core/types'

// 2. 添加方法实现
/**
 * 方法说明
 */
export async function yourMethod(params: YourParams): Promise<YourResult> {
  try {
    return await callNativeMethodAsync<YourResult>('yourMethod', params)
  } catch (error) {
    xlogE('tag_bridge_call', `yourMethod, error:${error}`)
    return null
  }
}

// 3. 添加到模块导出对象（文件末尾）
export const device = {
  // ... 已有方法
  yourMethod, // ✅ 新增这一行
}

3. 完成

不需要修改其他文件，export * 会自动导出新方法。

使用示例

方法模板

异步方法（有返回值）

export async function methodName(params: ParamsType): Promise<ResultType | null> {
  try {
    return await callNativeMethodAsync<ResultType>('methodName', params)
  } catch (error) {
    xlogE('tag_bridge_call', `methodName, error:${error}`)
    return null
  }
}

同步方法（无返回值）

export function methodName(params: ParamsType): void {
  bridge.callNativeMethod('methodName', params)
}

带超时控制

export async function methodName(params: ParamsType): Promise<ResultType | null> {
  try {
    // 第三个参数是超时时间（毫秒），null 表示不超时
    return await callNativeMethodAsync<ResultType>('methodName', params, 3000)
  } catch (error) {
    xlogE('tag_bridge_call', `methodName, error:${error}`)
    return null
  }
}

添加新模块

如果现有模块都不合适，可以创建新模块：

1. 创建 src/api/yourmodule.ts
2. 实现方法并导出模块对象：

   export const yourmodule = {
     method1,
     method2,
   }

3. 在 src/api/index.ts 中添加：

   export * from './yourmodule'
   export { yourmodule } from './yourmodule'

4. 在 src/index.ts 中添加到默认导出：

   import { yourmodule } from './api/yourmodule'
   
   export default {
     // ... 其他模块
     yourmodule,
   }

注意事项

1. 方法名要与 Native 端约定的方法名一致
2. 添加完整的 JSDoc 注释
3. 使用 TypeScript 类型，不要用 any
4. 异常要捕获并记录日志
5. 记得在模块导出对象中添加新方法