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

JsBridge模块化管理完全指南JsModule与JSBridgeMethod注解深度解析【免费下载链接】JsBridgeA simpler, extendable bidirectional communication Frame between Android WebView and Javascript项目地址: https://gitcode.com/gh_mirrors/jsbrid/JsBridgeJsBridge 是一个轻量、可扩展的 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抽象类。它只有两个你必须知道的点必须重写getModuleName()返回模块名模块名就是 JS 端访问你的命名空间基类内置了getContext()和getWebView()方便模块内部直接操作 Activity 和 WebView以示例工程中的 Native 模块为例sample/src/main/java/com/apkfuns/jsbridgesample/module/NativeModule.javapublic class NativeModule extends JsModule { Override public String getModuleName() { return native; // JS 端通过 JsBridge.native 访问本模块 } }模块命名规则新手最常踩的坑规则说明不能为空空模块名会被框架直接忽略不加载符合 Java 变量命名只允许_、字母、数字支持点号分层如native.extendJS 端变成二级结构模块内部可以直接拿 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方法的参数必须是下表支持的类型框架会自动完成解析与转换Java 类型映射的 JS 类型Boolean / booleanBoolInteger / int、Float、Double、LongNumberStringStringJBCallbackfunctionJS 回调函数JBMapObjectJBArrayArray⚠️ 方法不能是static或abstract。4. 用 JBCallback 实现JS 等原生的异步回调很多场景拍照、定位是异步的把JBCallback作为参数原生完成后调用callback.apply(数据)即可把结果回传给 JSJSBridgeMethod 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.extendJS 端就形成了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注入的桥对象不一定立即可用。三种稳妥写法任选其一// 写法1ready 回调推荐 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.release()它会把模块持有的 WebView/Context 置空混淆后方法找不到按 jsbridge/proguard-rules.pro 保留JsModule及其子类JS 端报 undefined检查是否漏写JSBridgeMethod或模块根本没注册调用报模块解析错误模块名含非法字符命名只允许字母、数字、下划线、点号分层回调收不到数据JBCallback.apply()只支持基本类型、WritableJBArray、WritableJBMap其他对象会转为 String八、核心文件速查表模块基类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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考