企业官网建设流程全解析

JsBridge模块化管理完全指南：JsModule与@JSBridgeMethod注解深度解析

【免费下载链接】JsBridgeA simpler, extendable bidirectional communication Frame between Android WebView and Javascript项目地址: https://gitcode.com/gh_mirrors/jsbrid/JsBridge

JsBridge 是一个轻量、可扩展的 Android WebView 与 JavaScript 双向交互框架，它的核心设计就是模块化管理：原生能力被组织成一个个JsModule模块，方法通过@JSBridgeMethod注解暴露给 H5 页面调用。读完这篇完全指南，你只需几分钟就能上手 JsBridge 的模块机制，写出结构清晰、易扩展的混合应用。

一、为什么需要模块化管理

如果所有原生方法都堆在一个类里，随着业务增长（定位、拍照、支付、分享……），代码会迅速失控。JsBridge 给出的解法非常直观：

一个业务领域 = 一个JsModule子类；一个可被 H5 调用的方法 = 一个带@JSBridgeMethod注解的方法。

这样做的好处：

• 📦职责清晰：定位功能、相机功能各自成模块，互不干扰
• 🔌按需加载：不同页面可以只注入自己需要的模块
• 🧩分层组织：模块名支持点号分层，JS 侧呈树状结构调用
• 🛡️安全可控：H5 能调用什么，完全由你在原生端注册的方法决定，无需在 JS 端引入任何桥接文件

二、JsModule 模块：模块化管理的核心基类

所有自定义模块都继承自 jsbridge/src/main/java/com/apkfuns/jsbridge/module/JsModule.java 中定义的JsModule抽象类。它只有两个你必须知道的点：

1. 必须重写getModuleName()返回模块名，模块名就是 JS 端访问你的"命名空间"
2. 基类内置了getContext()和getWebView()，方便模块内部直接操作 Activity 和 WebView

以示例工程中的 Native 模块为例（sample/src/main/java/com/apkfuns/jsbridgesample/module/NativeModule.java）：

public class NativeModule extends JsModule { @Override public String getModuleName() { return "native"; // JS 端通过 JsBridge.native 访问本模块 } }

模块命名规则（新手最常踩的坑）：

模块内部可以直接拿 Context 做业务，例如：

@JSBridgeMethod public void loadNewPage(String url) { Intent it = new Intent(getContext(), WebViewActivity.class); it.putExtra("url", url); getContext().startActivity(it); }

三、@JSBridgeMethod 注解：把 Java 方法暴露给 JS

注解定义在jsbridge/src/main/java/com/apkfuns/jsbridge/module/JSBridgeMethod.java，是一个运行时注解，只有加了它的方法才会被注入 JS，相当于白名单机制。

1. 基本用法

@JSBridgeMethod public void toast(String msg) { Toast.makeText(getContext(), msg, Toast.LENGTH_SHORT).show(); }

默认Java 方法名 = JS 调用名，JS 端这样调用：

JsBridge.native.toast('hello JsBridge');

2. 自定义调用名

不想暴露真实方法名？用methodName属性重命名：

@JSBridgeMethod(methodName = "showTip") public void toast(String msg) { ... } // JS 端调用 JsBridge.native.showTip('...')

3. Java ↔ JS 参数类型映射表

@JSBridgeMethod方法的参数必须是下表支持的类型，框架会自动完成解析与转换：

⚠️ 方法不能是static或abstract。

4. 用 JBCallback 实现"JS 等原生"的异步回调

很多场景（拍照、定位）是异步的，把JBCallback作为参数，原生完成后调用callback.apply(数据)即可把结果回传给 JS：

@JSBridgeMethod public void takePhoto(final JBCallback success, final JBCallback errorCallback) { // 拍照完成后： success.apply(base64Str); // 成功回调 // 或 errorCallback.apply("拍照失败"); // 失败回调 }

对应 JS 端：

JsBridge.native.takePhoto(function(img) { ... }, function(err) { ... });

5. 用 JBMap 接收"对象参数"

想让 JS 调用像$.ajax那样传一个对象，就用JBMap接参，再从里面按需取值：

@JSBridgeMethod public void ajax(JBMap dataMap) { String url = dataMap.getString("url"); JBCallback success = dataMap.getCallback("success"); // 请求完成后 success.apply(返回数据) }

四、三种模块变体：静态模块、多层模块、监听模块

1. 静态模块 JsStaticModule —— 方法直接挂在 JsBridge 上

继承jsbridge/src/main/java/com/apkfuns/jsbridge/module/JsStaticModule.java中的JsStaticModule（它固定模块名为@static），方法会直接挂载到协议对象上，无需二级命名空间：

public class StaticModule extends JsStaticModule { @JSBridgeMethod public int getVersion() { return 10; } }

JS 端调用简洁直接：

var v = JsBridge.getVersion(); // 直接调用，无模块前缀

2. 多层模块 JsMultiModule —— 点号分层的命名空间

jsbridge/src/main/java/com/apkfuns/jsbridge/module/JsMultiModule.java支持用数组声明多层模块名，示例sample/src/main/java/com/apkfuns/jsbridgesample/module/MultiLayerModule.java返回"native.extend"，JS 端就形成了JsBridge.native.extend.toast(...)的树状调用结构。框架注入时会自动创建中间层对象，你不需要手动维护层级。

3. 监听模块 JsListenerModule —— 原生主动喊话 JS 的通道

双向交互的另一半：原生 → JS推送。jsbridge/src/main/java/com/apkfuns/jsbridge/module/JsListenerModule.java提供callJsListener()，可在原生生命周期事件里主动执行 JS 函数：

public class ListenerModule extends JsListenerModule { @Override public String getModuleName() { return "page"; } public static void onResume(IWebView webView, Object... args) { callJsListener("MyBridge.page.onResume", webView, args); } }

典型用途：页面 onResume/onPause 时通知 H5 刷新状态，实现"回到页面自动刷新"。

五、模块注册的两种方式：默认注册 vs 动态注册

模块写好后要注册才能被注入。JsBridge 提供两种姿势（见jsbridge/src/main/java/com/apkfuns/jsbridge/JsBridgeConfigImpl.java与JsBridge.java）：

方式一：默认注册（全局公用，所有页面自动加载）

JsBridgeConfig.getSetting().registerDefaultModule(NativeModule.class);

方式二：动态注册（仅当前页面生效，推荐用于页面级能力）

jsBridge = JsBridge.loadModule(new NativeModule());

经验法则：登录态、埋点这类全局能力用默认注册；拍照、扫码这类页面能力用动态注册，保持每个 WebView 实例轻量。

六、JS 端调用与初始化时机（新手必看）

JS 执行是异步的，injectJs注入的桥对象不一定立即可用。三种稳妥写法任选其一：

// 写法1：ready 回调（推荐） window.onJsBridgeReady = function () { JsBridge.native.toast('bridge ready!'); }; // 写法2：事件监听 document.addEventListener('onJsBridgeReady', function(){ ... }); // 写法3：存在性判断 if (window.JsBridge) { JsBridge.native.toast('ok'); }

onJsBridgeReady这个函数名可通过JsBridgeConfig的setLoadReadyMethod自定义，协议名JsBridge也可通过setProtocol改成你自己的前缀。

七、避坑清单：这些细节决定了稳定性

八、核心文件速查表

• 模块基类：jsbridge/src/main/java/com/apkfuns/jsbridge/module/JsModule.java
• 静态模块：jsbridge/src/main/java/com/apkfuns/jsbridge/module/JsStaticModule.java
• 多层模块：jsbridge/src/main/java/com/apkfuns/jsbridge/module/JsMultiModule.java
• 监听模块：jsbridge/src/main/java/com/apkfuns/jsbridge/module/JsListenerModule.java
• 方法注解：jsbridge/src/main/java/com/apkfuns/jsbridge/module/JSBridgeMethod.java
• 回调接口：jsbridge/src/main/java/com/apkfuns/jsbridge/module/JBCallback.java
• 参数对象/数组：jsbridge/src/main/java/com/apkfuns/jsbridge/module/JBMap.java、JBArray.java
• 配置与注册：jsbridge/src/main/java/com/apkfuns/jsbridge/JsBridgeConfig.java
• 完整示例模块：sample/src/main/java/com/apkfuns/jsbridgesample/module/

小结：JsBridge 的模块化管理把"暴露什么、怎么调用、如何回调"拆成了三个正交概念——JsModule管命名空间、@JSBridgeMethod管方法白名单、JBCallback管异步回传。掌握这套组合拳，你就能把任意原生能力安全、整洁地开放给 H5，这正是它比传统addJavascriptInterface方案更优雅的地方。

【免费下载链接】JsBridgeA simpler, extendable bidirectional communication Frame between Android WebView and Javascript项目地址: https://gitcode.com/gh_mirrors/jsbrid/JsBridge