rxjs-native-bridge简介

基于 RxJS 对传统 js-bridge 进行封装的 Web 侧通信库，
将 Native → Web 的调用建模为 事件流 + 状态快照，
用于解决多模块监听、回调耦合和状态同步问题。

底层基于以下 js-bridge 实现：

• Android：https://github.com/uknownothingsnow/JsBridge
• iOS：https://github.com/marcuswestin/WebViewJavascriptBridge

使用

安装依赖 npm install rxjs rxjs-native-bridge

初始化 js-bridge

在项目入口引入库即可完成 js-bridge 初始化：

// main.ts / index.ts
import 'rxjs-native-bridge'

扩展

// import { jsBridge, rxJsBridge, JSBridge, RxJSBridge } from 'rxjs-native-bridge'
// 自定义jsBridge扩展继承 JSBridge
// 自定义RxJSBridge扩展继承 RxJSBridge

不使用 RxJS（仅使用原始 js-bridge）

如果你只需要基础的 js-bridge 能力，可以直接使用导出的 jsBridge：

import { jsBridge } from 'rxjs-native-bridge'

js调用native

 jsBridge.callHandler('handlerName', { num: 1 }, res => {
   console.log(res)
 }): void

js注册方法供native调用

 jsBridge.registerHandler('handlerName', (params, callback) => {
  console.log('native 参数', params)
  callback({ name: 'hello' })
}): void

使用rxjs

js调用native全局回调值拦截器

import { rxJsBridge } from 'rxjs-native-bridge'
rxJsBridge.useCallInterceptor<{ data: unknown }>(res => {
  if (!res) throw new Error('native error') // 抛出错误后会被订阅者订阅到错误而不是成功
  if (res?.data) return res.data
}): RxJsBridge 

js调用native

rxJsBridge
.call<{ num: number }, { name: string }>('test', { num: 1 })
.subscribe(res => {
  console.log(res.name)
})

js注册方法供native调用

/**
 * 注意：
 * register 注册的是「状态型 handler」
 * Native 调用该 handler 时，回调返回的是当前通过 setState 设置的状态值，
 * 而不是等待 JS 侧逻辑执行完成后的结果。
 *
 * 因此建议：
 * - 在项目入口统一 register
 * - 在各业务模块中通过 on / once 监听事件
 */

// 注册方法供 Native 调用（建议在项目入口统一注册）
rxJsBridge.register('handlerName'): RxJSBridge

// 设置 / 更新该 handler 的状态值（Native 调用时会同步返回此值）
rxJsBridge.setState('handlerName', { name: 'hello' }): void

// 获取该 handler 当前的状态值
rxJsBridge.getState('handlerName'): unknown | undefined

// 删除该 handler 的状态（删除后 Native 调用回调为 null）
rxJsBridge.delState('handlerName'): void

// 清空所有 handler 的状态（所有回调均返回 null）
rxJsBridge.clearState(): void

// 在其他业务模块中监听 Native 对该 handler 的调用
const sub = rxJsBridge.on('handlerName').subscribe(({ params }) => {
  console.log('Native 传入的参数：', params)
})

// 取消监听
sub.unsubscribe()

监听执行并自动取消

rxJsBridge.once('handlerName').subscribe(({ params }) => {
  console.log('native 参数', params)
})

or

rxJsBridge
  .event('handlerName')
  .pipe(take(1))
  .subscribe(({ params }) => {
    console.log('native 参数', params)
  })

注意：

• once 和 event 在未注册时会自动执行 register
• register 仅负责注册 handler，不会触发监听

同时注册并监听事件

// 链式调用
const sub = rxJsBridge
 .register('handlerName')
 .on('handlerName')
 .subscribe(({ params }) => {
  console.log('native 参数', params)
})
sub.unsubscribe()  // 取消监听
// or
rxJsBridge.once('handlerName').subscribe(({ params }) => {
  console.log('native 参数', params)
})
// or
const sub = rxJsBridge
.event('handlerName')
.subscribe(({ params }) => {
  console.log('native 参数', params)
})

sub.unsubscribe()  // 取消监听

导出说明

export { jsBridge, rxJsBridge, JSBridge, RxJSBridge }

• jsBridge / rxJsBridge
  已初始化的 单例实例，可直接使用（推荐方式）。

• JSBridge / RxJSBridge
  未初始化的类，用于 自定义扩展或继承。
  可通过其静态方法 getInstance() 获取单例实例；
  若直接 new 使用，需要自行完成初始化流程。

工具api

平台判断

jsBridge.isAndroid: boolean // 是否运行在 Android WebView 环境。

jsBridge.isiOS: // boolean是否运行在 iOS WebView 环境。

环境判断

jsBridge.isNative(): boolean // 判断当前是否处于 Native WebView 环境。

设计理念

传统 js-bridge 通常采用「请求 - 回调」模型，在复杂业务场景中容易出现：

• 多模块同时监听同一 Native 调用
• 回调耦合、状态难以复用
• 调用顺序和生命周期难以管理

rxjs-native-bridge 将 Native → Web 的调用建模为：

• 事件流（Observable）：用于分发调用事件
• 状态快照（BehaviorSubject）：用于同步当前状态

从而实现：

• 统一注册，分散监听
• 状态与事件解耦
• 自动取消订阅，避免内存泄漏

构建项目

npm run build