更新记录

1.0.5（2025-08-01）

代码优化，修复部分 bug

1.0.3（2025-07-25）

代码优化

1.0.2（2025-07-24）

跟进 ios 端功能

平台兼容性

uni-app x

native-webview

UniApp UTS 原生 WebView 组件，提供增强的 WebView 功能，支持 JavaScript 桥接、文件选择器、权限管理、视频优化和智能缓存。

功能特性

• 🌐 原生 WebView 组件：基于平台原生 WebView 实现，性能优异
• 🔗 JavaScript 桥接：支持 Web 页面与原生应用的双向通信
• 🔐 智能权限管理：自动检测并申请所需权限（摄像头、麦克风、存储）
• 🎬 视频播放优化：硬件加速、全屏支持、黑屏修复
• ⚡ 智能缓存系统：JavaScript/CSS/图片文件缓存，提升加载性能
• 🎯 导航控制：提供前进、后退、刷新等完整导航功能
• 📱 生命周期管理：完整的 WebView 创建、加载、销毁流程

平台支持

注意：当前版本主要支持 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>
      <button @click="cacheResources">缓存资源</button>
    </view>
  </view>
</template>

2. 组件配置

// 导入缓存功能
import { cacheJsFile } from '@/uni_modules/native-webview'

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()
    },

    // 缓存常用资源
    cacheResources() {
      // 缓存 JavaScript 文件
      cacheJsFile('https://cdn.jsdelivr.net/npm/vue@3/dist/vue.global.js')
      cacheJsFile('https://unpkg.com/axios/dist/axios.min.js')
    }
  }
}

API 文档

组件属性

组件事件

组件方法

插件方法

桥接接口说明

原生 → Web

// 原生调用 Web 页面方法
window.callWebViewReceiveMessageFromNative(data)

Web → 原生

// Web 页面调用原生方法
window.NativeBridge.callNative(params)

权限要求

组件会自动申请以下权限：

<!-- 网络访问 -->
<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" />

视频播放优化

自动优化特性

• 硬件加速：自动启用硬件加速提升渲染性能
• 自动播放：支持视频自动播放（mediaPlaybackRequiresUserGesture = false）
• 全屏支持：自动处理视频全屏播放事件
• 混合内容：支持 HTTPS 页面加载 HTTP 视频资源

视频优化配置

// 视频标签优化属性会自动注入
video.setAttribute('playsinline', 'true')
video.setAttribute('webkit-playsinline', 'true')
video.style.backgroundColor = 'transparent'

智能缓存系统

缓存特性

• MD5 命名：基于文件 URL 的 MD5 值命名，避免冲突
• MIME 检测：自动检测文件 MIME 类型，正确服务内容
• 请求拦截：自动拦截 WebView 请求，优先使用缓存文件
• 性能提升：减少网络请求，提升页面加载速度

支持的缓存类型

• JavaScript 文件：.js
• CSS 样式文件：.css
• 图片文件：.png, .jpg, .gif, .webp, .svg
• 字体文件：.woff, .woff2, .ttf

缓存使用示例

import { cacheJsFile } from '@/uni_modules/native-webview'

// 缓存常用的第三方库
cacheJsFile('https://cdn.jsdelivr.net/npm/vue@3/dist/vue.global.js')
cacheJsFile('https://unpkg.com/axios/dist/axios.min.js')
cacheJsFile('https://cdn.jsdelivr.net/npm/lodash@4/lodash.min.js')

// 缓存项目相关资源
cacheJsFile('https://your-cdn.com/common.js')
cacheJsFile('https://your-cdn.com/styles.css')

实现原理

Android 端架构

1. Vue 组件层 (index.vue)

• 组件生命周期管理
• 属性监听和事件处理
• 对外暴露的方法接口

2. UTS 桥接层 (index.uts)

• Activity 结果回调处理
• 缓存文件下载管理
• 连接 Vue 组件和原生实现

3. 原生实现层

• WebViewUtil.kt：WebView 核心配置、文件选择器、缓存拦截
• JsInterface.kt：JavaScript 桥接接口实现
• CacheUtil.kt：智能缓存系统实现

WebView 增强配置

// 主要配置项
settings.javaScriptEnabled = true                    // 启用 JavaScript
settings.domStorageEnabled = true                    // DOM 存储
settings.allowFileAccess = true                      // 文件访问
settings.mediaPlaybackRequiresUserGesture = false   // 自动播放媒体
settings.mixedContentMode = MIXED_CONTENT_ALWAYS_ALLOW  // 混合内容
webView.setLayerType(View.LAYER_TYPE_HARDWARE, null) // 硬件加速

缓存机制实现

1. MD5 文件命名：CacheUtil.getCacheFileName() 生成唯一文件名
2. 请求拦截：shouldInterceptRequest() 拦截 WebView 请求
3. 缓存服务：优先返回本地缓存文件，降级到网络请求
4. MIME 类型：根据文件扩展名自动设置正确的 Content-Type

技术规格

• 最低 Android SDK: 21 (Android 5.0)
• 最低 HBuilderX 版本: 3.7.0
• 开发框架: UTS (TypeScript for UniApp)
• 组件类型: UTS Vue 组件
• WebView 引擎: Android WebView (Chromium)
• 硬件加速: 支持 Android 5.0+ 硬件加速
• 文件系统: FileProvider 安全文件访问
• 缓存机制: MD5 + MIME 类型检测

性能优化建议

1. 合理使用 setData：避免频繁调用，建议批量传输数据
2. 预缓存资源：提前缓存常用的 JavaScript 和 CSS 文件
3. 及时清理资源：组件销毁时会自动清理 WebView 资源
4. 优化 Web 页面：减少不必要的 DOM 操作和网络请求
5. 控制并发：避免同时加载多个复杂的 WebView
6. 视频优化：使用适当的视频格式和编码，启用硬件解码
7. 缓存策略：根据业务需求合理配置缓存文件

开发文档

• UTS 语法参考
• UTS API 插件开发
• UTS Vue 组件开发
• Hello UTS 示例项目

常见问题

Q: 视频播放出现黑屏怎么办？

A: 插件已自动注入修复脚本，如仍有问题可检查：

1. 视频格式是否为 WebView 支持的格式
2. 是否启用了硬件加速
3. 检查网络连接和视频 URL 是否可访问

Q: 缓存文件过多怎么办？

A: 缓存文件存储在应用缓存目录，会随应用卸载自动清理。如需手动清理，可以：

1. 使用系统设置清理应用缓存
2. 应用更新时会自动清理旧缓存

Q: JavaScript 桥接不工作？

A: 检查以下几点：

1. 确保 Web 页面已完全加载
2. 检查 window.NativeBridge 是否存在
3. 确保回调函数 callWebViewReceiveMessageFromNative 已定义

版本历史

• v1.2.0: 重大更新

  • ✅ 新增智能缓存系统（MD5 + MIME 检测）
  • ✅ 请求拦截机制实现缓存服务
  • ✅ 缓存文件下载功能（cacheJsFile）
  • 🔧 性能优化和内存管理改进

• v1.0.0: 初始版本

  • ✅ Android WebView 基础功能
  • ✅ JavaScript 桥接
  • ❌ iOS 平台待开发

贡献指南

欢迎贡献代码和提出建议！特别是：

1. iOS 平台实现：基于 WKWebView 的完整实现
2. 功能增强：更多 WebView 配置选项和缓存策略
3. 性能优化：内存管理和渲染性能提升
4. 文档完善：更多使用示例和最佳实践
5. 缓存优化：更智能的缓存策略和清理机制