当前位置： 首页 > article >正文

webview_flutter_android 4.3.0使用

article 2025/1/27 13:29:28

webview_flutter_android 4.3.0 使用简介

版本：适合未使用前的阅读

文档应包含以下10个核心章节：

  • 一、核心类说明
  • 二、参数类型详解
  • 三、高级配置API
  • 四、性能优化配置
  • 五、调试工具
  • 六、必要配置
  • 七、扩展功能与辅助类
  • 八、生命周期管理
  • 九、高级交互示例
  • 十、疑难解答

==================================================

一、核心类说明

==================================================

1. AndroidWebViewController 类

/// Android平台WebView的核心控制器，继承自PlatformWebViewController
/// 用于管理WebView的生命周期、配置和交互
class AndroidWebViewController {

  /// 构造函数
  /// @param params - 平台WebViewController创建参数
  AndroidWebViewController(PlatformWebViewControllerCreationParams params);

  /// 设置用户代理字符串
  /// @param userAgent - 要设置的UA字符串，传null则使用系统默认
  Future<void> setUserAgent(String? userAgent);

  /// 设置WebView背景颜色
  /// @param color - 使用Flutter的Color对象（支持透明度）
  Future<void> setBackgroundColor(Color color);

  /// 配置JavaScript执行模式
  /// @param mode - JavaScript模式枚举：
  ///   - disabled: 完全禁用JS执行
  ///   - unrestricted: 允许执行所有JS代码（包括alert等）
  Future<void> setJavaScriptMode(JavaScriptMode mode);

  /// 添加JavaScript通信通道
  /// @param name - 通道名称（需与JS端保持一致）
  /// @param onMessageReceived - 消息接收回调
  /// 示例：JS端调用 window.FlutterBridge.postMessage('Hello')
  Future<void> addJavaScriptChannel(
    String name, {
    required void Function(JavaScriptMessage) onMessageReceived,
  });

  /// 加载URL请求
  /// @param url - 要加载的URL地址
  /// @param headers - 附加的HTTP请求头（可选）
  Future<void> loadRequest(String url, {Map<String, String>? headers});

  /// 执行JavaScript代码
  /// @param javascript - 要执行的JS代码字符串
  /// @return 执行结果（可能为null）
  Future<String?> evaluateJavascript(String javascript);

  /// 清除缓存（包括内存和磁盘缓存）
  Future<void> clearCache();
}

2. AndroidNavigationDelegate 类

/// 处理WebView导航事件的委托类
class AndroidNavigationDelegate {

  /// 构造函数
  /// @param params - 平台导航委托创建参数
  AndroidNavigationDelegate(PlatformNavigationDelegateCreationParams params);

  /// 导航请求回调
  /// 参数：
  ///   - request: 包含url和isMainFrame的导航请求对象
  /// 返回值：
  ///   - NavigationDecision.navigate: 允许导航
  ///   - NavigationDecision.prevent: 阻止导航
  NavigationRequestCallback onNavigationRequest;

  /// 页面开始加载回调
  /// @param url - 开始加载的URL
  PageStartedCallback onPageStarted;

  /// 页面加载完成回调
  /// @param url - 加载完成的URL
  PageFinishedCallback onPageFinished;

  /// 资源加载错误回调
  /// @param error - 包含errorCode和description的错误对象
  WebResourceErrorCallback onWebResourceError;
}

3. AndroidWebViewWidget 类

/// Android平台的WebView渲染组件
class AndroidWebViewWidget extends StatelessWidget {
  
  /// 构造函数
  /// @param controller - WebViewController实例（必须）
  /// @param navigationDelegate - 导航委托实例（可选）
  /// @param creationParams - 创建参数（可选）
  const AndroidWebViewWidget({
    required PlatformWebViewController controller,
    PlatformNavigationDelegate? navigationDelegate,
    PlatformWebViewCreationParams? creationParams,
  });

  /// 手势识别器集合
  /// 用于处理WebView内的手势交互（如滑动、长按等）
  final Set<Factory<OneSequenceGestureRecognizer>>? gestureRecognizers;

  /// WebView创建完成回调
  /// 在WebView实例化完成后触发
  final WebViewCreatedCallback? onWebViewCreated;

  /// 是否启用缩放功能
  /// 默认false（禁用双指缩放）
  final bool zoomEnabled;
}

==================================================

二、参数类型详解

==================================================

1. JavaScriptMode 枚举

/// JavaScript执行模式配置
enum JavaScriptMode {
  disabled,    // 完全禁用JavaScript
  unrestricted // 允许执行所有JavaScript代码
}

2. NavigationRequest 类

/// 导航请求信息封装
class NavigationRequest {
  final String url;       // 请求的目标URL
  final bool isMainFrame; // 是否为主框架请求
}

3. WebResourceError 类

/// Web资源错误信息
class WebResourceError {
  final int errorCode;     // 错误代码（参考Android WebViewClient错误码）
  final String description;// 错误描述（英文原文）
}

==================================================

三、高级配置API

==================================================

1. AndroidWebViewCookieManager 类

/// Cookie管理工具类
class AndroidWebViewCookieManager {
  
  /// 设置Cookie
  /// @param cookie - WebViewCookie对象
  Future<void> setCookie(WebViewCookie cookie);
}

/// Cookie数据结构
class WebViewCookie {
  final String name;   // Cookie名称
  final String value;  // Cookie值
  final String domain; // 作用域
  final String path;   // 路径
}

2. 文件选择器配置

/// 注册文件选择处理器
AndroidWebViewPlatform.instance.registerFileChooserHandler(
  (FileChooserParams params) async {
    // 返回用户选择的文件路径列表
    return await FilePicker.platform.pickFiles();
  }
);

3. 初始化配置

/// 平台初始化配置
AndroidWebViewPlatform.instance.initialize(
  androidInitializationSettings: AndroidInitializationSettings(
    hardwareAcceleration: true,  // 启用硬件加速渲染
    enableHybridComposition: true, // 混合合成模式（必须为true）
    useTextureView: false,       // 使用SurfaceView替代TextureView
  )
);

==================================================

四、性能优化配置

==================================================

1. 缓存策略

AndroidWebViewPlatform.instance.setCacheMode(
  cacheMode: AndroidCacheMode.loadElseNetwork, // 优先使用缓存
  maxCacheSize: 100 * 1024 * 1024 // 最大缓存100MB
);

2. 性能监控指标

/// 可用监控指标枚举
enum AndroidPerformanceMetric {
  navigationTiming,  // 导航时间统计
  resourceTiming,    // 资源加载时间
  frameTiming,       // 渲染帧率
}

==================================================

五、调试工具

==================================================

/// 启用WebView内容调试（需在debug模式）
if (kDebugMode) {
  AndroidWebView.setWebContentsDebuggingEnabled(true);
}

==================================================

六、必要配置

==================================================

AndroidManifest.xml 权限

<!-- 必须添加以下权限 -->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

build.gradle 最低配置

android {
    compileSdkVersion 33
    minSdkVersion 20  // 最低支持Android 5.0
    ...
}

==================================================

七、扩展功能与辅助类

==================================================

1. AndroidWebViewPlatform 类

/// Android平台WebView的全局配置入口
class AndroidWebViewPlatform {

  /// 单例实例
  static final instance = AndroidWebViewPlatform();

  /// 初始化平台设置
  /// @param androidInitializationSettings - Android专用初始化参数
  void initialize({
    required AndroidInitializationSettings androidInitializationSettings,
  });

  /// 注册文件选择处理器
  /// @param handler - 处理函数需返回文件路径列表
  void registerFileChooserHandler(
    Future<List<String>?> Function(FileChooserParams params) handler
  );
}

2. AndroidInitializationSettings 类

/// Android平台初始化参数配置
class AndroidInitializationSettings {
  final bool hardwareAcceleration; // 是否启用硬件加速（默认true）
  final bool enableHybridComposition; // 启用混合合成模式（必须为true）
  final bool useTextureView; // 使用TextureView替代SurfaceView（默认false）
}

3. FileChooserParams 类

/// 文件选择器参数封装
class FileChooserParams {
  final bool allowMultiple; // 是否允许多选
  final List<String> mimeTypes; // 允许的MIME类型
}

==================================================

八、生命周期管理

==================================================

1. WebView创建流程

  1. 初始化控制器：
   final controller = AndroidWebViewController(
     PlatformWebViewControllerCreationParams()
   );
  1. 配置导航委托：
controller.navigationDelegate = AndroidNavigationDelegate(
  onNavigationRequest: (request) {
    if (!_validateUrl(request.url)) {
      return NavigationDecision.prevent;
    }
    return NavigationDecision.navigate;
  }
);
  1. 构建Widget：
AndroidWebViewWidget(controller: controller)

2. 资源释放流程

/// 在State的dispose方法中释放资源
@override
void dispose() {
controller.dispose(); // 释放控制器
_cookieManager.clear(); // 清理Cookie
super.dispose();
}

==================================================

九、高级交互示例

  1. JS与Flutter双向通信
/// Flutter端注册通道
controller.addJavaScriptChannel(
'Scanner',
onMessageReceived: (message) {
final result = await scanBarcode();
controller.evaluateJavascript('onScanResult("$result")');
}
);


/// JS端调用
window.Scanner.postMessage('startScan');
  1. 自定义下载管理器
controller.navigationDelegate = AndroidNavigationDelegate(
onNavigationRequest: (request) {
if (request.url.endsWith('.apk')) {
_startDownload(request.url);
return NavigationDecision.prevent;
}
return NavigationDecision.navigate;
}
);

==================================================

十、疑难解答

  1. 混合合成模式异常
    症状：Android 10+设备白屏
    解决方案：
AndroidWebViewPlatform.instance.initialize(
  androidInitializationSettings: AndroidInitializationSettings(
    enableHybridComposition: true, // 必须启用
  )
);
  1. Cookie存储失效
    症状：登录状态无法保持
    解决方案：
<!-- 在AndroidManifest.xml中添加 -->
<application
  android:usesCleartextTraffic="true"
  android:allowBackup="false">
  1. 文件上传兼容性问题
    症状：部分机型无法选择文件
    解决方案：
// 在文件选择回调中处理路径转换
registerFileChooserHandler((params) async {
  final result = await FilePicker.platform.pickFiles();
  return result?.files
    .map((f) => f.path?.replaceFirst('file://', ''))
    .toList();
});

==================================================

文档更新日志

补充混合合成模式配置说明

增加文件选择器路径处理示例

完善生命周期管理章节


http://www.kler.cn/a/520585.html

相关文章：

  • 日志收集Day007
  • 99.17 金融难点通俗解释：归母净利润
  • 工厂模式 - 工厂方法模式、抽象工厂模式
  • Excel制作合同到期自动提醒！
  • 基于回归分析法的光伏发电系统最大功率计算simulink建模与仿真
  • 定时器按键tim_key模版
  • java 字符串日期字段格式化前端显示
  • 并发操作下如何加锁，自动释放锁，异常情况可以主动释放锁
  • gitee——报错修改本地密码
  • 51单片机开发：独立键盘实验
  • 数据结构：log-structed结构MemTableSSTable
  • 代码工艺：实践 Spring Boot TDD 测试驱动开发
  • C#常考随笔2：函数中多次使用string的+=处理，为什么会产生大量内存垃圾（垃圾碎片），有什么好的方法可以解决？
  • SocketCAN
  • WebSocket 心跳机制：确保连接稳定与实时性
  • 【Rust自学】15.5. Rc＜T＞：引用计数智能指针与共享所有权
  • ubuntu 更新24LTS中断导致“系统出错且无法恢复，请联系系统管理员”
  • 【MySQL】--- 复合查询 内外连接
  • 使用scikit-learn中的KNN包实现对鸢尾花数据集或者自定义数据集的的预测
  • oracle 分区表介绍
  • [特殊字符]【计算机视觉】r=2 采样滤波器全解析 ✨
  • leetcode_链表 876.链表的中间节点
  • 利用Redis实现数据缓存
  • docker安装MySQL8:docker离线安装MySQL、docker在线安装MySQL、MySQL镜像下载、MySQL配置、MySQL命令
  • PHP反序列化练习
  • Semantic Kernel - Kernel理解