跨平台开发实战：uniapp中JS调用Java原生模块完整指南
哎，用uniapp开发时是不是总遇到这种情况？页面效果做得很炫，可一调摄像头、GPS这些硬件功能就抓瞎？别急，今天咱们就破译这个"跨次元通话"的密码本！
（分割线）
??一、基础认知篇：这玩意到底啥原理？??
??为什么uniapp能调用Java？?? 说白了就是靠原生渲染引擎架桥。当JS想调原生功能时，会通过uni-app框架的??Native.js??模块把指令翻译成Android能听懂的语言。
??必须掌握的三个关键点??：
- 原生模块必须封装成??Android Library??（.aar文件）
- 需要配置??build.gradle??声明依赖
- 通过??uni.requireNativePlugin??获取模块实例
举个栗子：
javascript复制const barcodeModule = uni.requireNativePlugin('MyBarcodeScanner')
（分割线）
??二、实战操作篇：手把手搭桥??
??怎么创建自定义原生模块？?? 分五步走：
- 在Android Studio新建??Module??（选Android Library）
- 编写带@UniJSMethod注解的Java类
- 生成aar文件扔进uniapp项目的??nativeplugins??目录
- 在manifest.json里配置模块信息
- 真机调试别用模拟器（很多硬件功能不支持）
??配置清单示例??：
json复制"nativePlugins": [{ "type": "module", "name": "MyBarcodeScanner", "class": "com.mycompany.scanner.BarcodeImpl" }]
（分割线）
??三、参数传递秘籍??
??JS和Java怎么传复杂数据？?? 记住这个转换法则：
| JS数据类型 | Java接收类型 | 处理技巧 |
|---|---|---|
| Object | JSONObject | 用optString避免空指针 |
| Array | JSONArray | 遍历时判断length > 0 |
| Function | JSCallback | 必须用@UniJSMethod注解 |
| File | String | 传文件路径而不是二进制流 |
??典型错误案例??：
javascript复制// JS错误写法：直接传对象 barcodeModule.scan({quality: 0.8}) // Java正确接收方式： @UniJSMethod public void scan(JSONObject options) { double quality = options.optDouble("quality", 0.5); }
（分割线）
??四、异步通信怎么玩转??
??回调函数总是不触发怎么办？?? 记住这三板斧：
- 在JS里用Promise封装异步操作
- Java端使用??UniJSCallback??提交结果
- 处理线程切换（重点！）
??完整示例流程??：
javascript复制// JS端 function scanBarcode() { return new Promise((resolve, reject) => { barcodeModule.scan(res => { res.code ? resolve(res) : reject('扫描失败') }) }) }
java复制// Java端 @UniJSMethod public void scan(UniJSCallback callback) { new Thread(() -> { //...扫描操作 JSONObject result = new JSONObject(); callback.invoke(result); }).start(); }
（分割线）
??五、避坑指南（血泪经验）??
??模块加载失败怎么排查??？按这个顺序检查：
- aar文件是否放在??nativeplugins/模块名/android??目录
- 模块名是否在manifest.json里拼写错误
- 主模块的build.gradle是否添加依赖：
gradle复制implementation project(':MyBarcodeScanner')
??性能优化技巧??：
- 频繁调用的方法做成??单例模式??
- 大数据传输用??文件路径??代替base64
- 图片处理走??本地缓存路径??
（分割线）
??六、灵魂拷问环节??
??Q：为什么我照着文档写还是报ClassNotFound？??
A：九成是因为没在??settings.gradle??添加模块声明：
gradle复制include ':MyBarcodeScanner' project(':MyBarcodeScanner').projectDir = new File('../nativeplugins/MyBarcodeScanner/android')
??Q：能直接调用系统自带的功能吗？??
A：可以但没必要！建议通过??uni原生插件市场??找现成封装好的模块，比如：
- 相机调用用??uni-camera??
- 蓝牙用??uni-ble??
- 文件管理用??uni-file??
??Q：调试时怎么查看原生日志？??
A：两个神器：
- Android Studio的??Logcat??
- 在HBuilderX里开启【原生日志输出】
（分割线）
??个人私房建议??
干了这么多年跨平台开发，发现个真理：??别把所有鸡蛋放在一个篮子里??！敏感操作比如支付、生物识别，还是老老实实走各自平台的原生实现。uniapp的交互方案最适合这三类场景：
- 硬件功能扩展（扫码、NFC）
- 性能敏感操作（图像处理）
- 复用现有Java库（比如企业内部的加密算法）
最后送大家一句：善用插件市场（https://ext.dcloud.net.cn），能省至少50%的开发时间！遇到问题多查社区帖子，你会发现踩过的坑早有人填平了。