更新记录
1.0.0(2025-07-10)
初始版本,暂时支持 Android,iOS 后续跟进
平台兼容性
uni-app x
Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
---|---|---|---|---|---|
- | - | 7.0 | × | × | × |
native-webview
UniApp UTS 原生 WebView 组件,提供增强的 WebView 功能,支持 JavaScript 桥接、文件选择器和权限管理。
功能特性
- 🌐 原生 WebView 组件:基于平台原生 WebView 实现,性能优异
- 🔗 JavaScript 桥接:支持 Web 页面与原生应用的双向通信
- 📁 文件选择器:支持图片/视频选择、拍照和录像功能
- 🔐 智能权限管理:自动检测并申请所需权限(摄像头、麦克风、存储)
- 🎯 导航控制:提供前进、后退、刷新等完整导航功能
- 📱 生命周期管理:完整的 WebView 创建、加载、销毁流程
平台支持
功能 | Android | iOS | HarmonyOS |
---|---|---|---|
WebView 基础功能 | ✅ API 21+ | ❌ 待开发 | ✅ 计划支持 |
JavaScript 桥接 | ✅ 完整支持 | ❌ 待开发 | ✅ 计划支持 |
文件选择器 | ✅ 完整支持 | ❌ 待开发 | ✅ 计划支持 |
权限管理 | ✅ 自动处理 | ❌ 待开发 | ✅ 计划支持 |
注意:当前版本主要支持 Android 平台,iOS 平台正在开发中。
安装使用
1. 导入组件
<template>
<view class="container">
<native-webview
ref="webview"
:url="webUrl"
@webviewCallback="onWebViewCallback"
/>
<view class="controls">
<button @click="sendDataToWeb">发送数据</button>
<button @click="goBack">返回</button>
<button @click="goForward">前进</button>
<button @click="reload">刷新</button>
</view>
</view>
</template>
2. 组件配置
export default {
data() {
return {
webUrl: 'https://example.com'
}
},
methods: {
// 接收来自 Web 页面的数据
onWebViewCallback(data) {
console.log('收到Web页面数据:', data)
// 处理 Web 页面传递的数据
},
// 向 Web 页面发送数据
sendDataToWeb() {
this.$refs.webview.setData('Hello from Native App!')
},
// 导航控制
goBack() {
this.$refs.webview.goBack()
},
goForward() {
this.$refs.webview.goForward()
},
reload() {
this.$refs.webview.reload()
}
}
}
API 文档
组件属性
属性名 | 类型 | 默认值 | 说明 |
---|---|---|---|
url | String | "about:blank" | 要加载的网页 URL |
组件事件
事件名 | 参数 | 说明 |
---|---|---|
webviewCallback | data: String | Web 页面调用原生时触发,参数为传递的数据 |
组件方法
方法名 | 参数 | 返回值 | 说明 |
---|---|---|---|
setData | params: String | void | 向 Web 页面发送数据 |
goBack | - | void | WebView 后退 |
goForward | - | void | WebView 前进 |
reload | - | void | 刷新 WebView |
loadUrl | url: String | void | 加载指定 URL |
JavaScript 桥接
在 Web 页面中调用原生
<!DOCTYPE html>
<html>
<head>
<title>WebView Integration</title>
</head>
<body>
<h1>WebView 测试页面</h1>
<button onclick="callNative()">调用原生方法</button>
<button onclick="selectFile()">选择文件</button>
<div id="result"></div>
<script>
// 调用原生方法
function callNative() {
if (window.NativeBridge) {
NativeBridge.callNative('Hello from Web Page!')
} else {
console.log('NativeBridge not available')
}
}
// 文件选择(会自动触发原生文件选择器)
function selectFile() {
const input = document.createElement('input')
input.type = 'file'
input.accept = 'image/*'
input.click()
}
// 接收原生数据的回调函数
window.callWebViewReceiveMessageFromNative = function(data) {
document.getElementById('result') = '收到原生数据: ' + data
console.log('Received from native:', data)
}
// 页面加载完成
document.addEventListener('DOMContentLoaded', function() {
console.log('WebView page loaded')
})
</script>
</body>
</html>
桥接接口说明
原生 → Web
// 原生调用 Web 页面方法
window.callWebViewReceiveMessageFromNative(data)
Web → 原生
// Web 页面调用原生方法
window.NativeBridge.callNative(params)
文件选择器支持
支持的文件类型
- 图片文件:JPG, PNG, GIF, WebP 等
- 视频文件:MP4, AVI, MOV 等
- 拍照功能:直接调用摄像头拍照
- 录像功能:直接调用摄像头录像
权限要求
组件会自动申请以下权限:
<!-- 网络访问 -->
<uses-permission android:name="android.permission.INTERNET" />
<!-- 相机权限(拍照/录像) -->
<uses-permission android:name="android.permission.CAMERA" />
<!-- 麦克风权限(录像) -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<!-- 存储权限(文件选择) -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
实现原理
Android 端架构
1. Vue 组件层 (index.vue
)
- 组件生命周期管理
- 属性监听和事件处理
- 对外暴露的方法接口
2. UTS 桥接层 (index.uts
)
- Activity 结果回调处理
- 连接 Vue 组件和原生实现
3. 原生实现层
- WebViewUtil.kt:WebView 核心配置和文件选择器
- JsInterface.kt:JavaScript 桥接接口实现
WebView 配置特性
// 主要配置项
settings.javaScriptEnabled = true // 启用 JavaScript
settings.domStorageEnabled = true // DOM 存储
settings.allowFileAccess = true // 文件访问
settings.mediaPlaybackRequiresUserGesture = false // 自动播放媒体
settings.mixedContentMode = MIXED_CONTENT_COMPATIBILITY_MODE // 混合内容
文件选择器实现
- 智能类型检测:根据 HTML input accept 属性自动判断文件类型
- 权限动态申请:根据所需功能自动申请相应权限
- 多种选择方式:支持相册选择、拍照、录像等多种方式
- 安全文件处理:使用 FileProvider 安全地处理文件 URI
技术规格
- 最低 Android SDK: 21 (Android 5.0)
- 最低 HBuilderX 版本: 3.7.0
- 开发框架: UTS (TypeScript for UniApp)
- 组件类型: UTS Vue 组件
- WebView 引擎: Android WebView (Chromium)
性能优化建议
- 合理使用 setData:避免频繁调用,建议批量传输数据
- 及时清理资源:组件销毁时会自动清理 WebView 资源
- 优化 Web 页面:减少不必要的 DOM 操作和网络请求
- 控制并发:避免同时加载多个复杂的 WebView
开发文档
版本历史
- v1.0.0: 初始版本
- ✅ Android WebView 基础功能
- ✅ JavaScript 桥接
- ✅ 文件选择器和权限管理
- ❌ iOS 平台待开发
贡献指南
欢迎贡献代码和提出建议!特别是:
- iOS 平台实现:基于 WKWebView 的完整实现
- 功能增强:更多 WebView 配置选项
- 性能优化:内存管理和性能提升
- 文档完善:更多使用示例和最佳实践