更新记录

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  // 混合内容

文件选择器实现

  1. 智能类型检测:根据 HTML input accept 属性自动判断文件类型
  2. 权限动态申请:根据所需功能自动申请相应权限
  3. 多种选择方式:支持相册选择、拍照、录像等多种方式
  4. 安全文件处理:使用 FileProvider 安全地处理文件 URI

技术规格

  • 最低 Android SDK: 21 (Android 5.0)
  • 最低 HBuilderX 版本: 3.7.0
  • 开发框架: UTS (TypeScript for UniApp)
  • 组件类型: UTS Vue 组件
  • WebView 引擎: Android WebView (Chromium)

性能优化建议

  1. 合理使用 setData:避免频繁调用,建议批量传输数据
  2. 及时清理资源:组件销毁时会自动清理 WebView 资源
  3. 优化 Web 页面:减少不必要的 DOM 操作和网络请求
  4. 控制并发:避免同时加载多个复杂的 WebView

开发文档

版本历史

  • v1.0.0: 初始版本
    • ✅ Android WebView 基础功能
    • ✅ JavaScript 桥接
    • ✅ 文件选择器和权限管理
    • ❌ iOS 平台待开发

贡献指南

欢迎贡献代码和提出建议!特别是:

  1. iOS 平台实现:基于 WKWebView 的完整实现
  2. 功能增强:更多 WebView 配置选项
  3. 性能优化:内存管理和性能提升
  4. 文档完善:更多使用示例和最佳实践

隐私、权限声明

1. 本插件需要申请的系统权限列表:

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

暂无用户评论。

使用中有什么不明白的地方,就向插件作者提问吧~ 我要提问