webview_flutter_android 4.3.0使用

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()
   );

2. 配置导航委托：

controller.navigationDelegate = AndroidNavigationDelegate(
  onNavigationRequest: (request) {
    if (!_validateUrl(request.url)) {
      return NavigationDecision.prevent;
    }
    return NavigationDecision.navigate;
  }
);

3. 构建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');

2. 自定义下载管理器

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, // 必须启用
  )
);

2. Cookie存储失效
   症状：登录状态无法保持
   解决方案：

<!-- 在AndroidManifest.xml中添加 -->
<application
  android:usesCleartextTraffic="true"
  android:allowBackup="false">

3. 文件上传兼容性问题
   症状：部分机型无法选择文件
   解决方案：

// 在文件选择回调中处理路径转换
registerFileChooserHandler((params) async {
  final result = await FilePicker.platform.pickFiles();
  return result?.files
    .map((f) => f.path?.replaceFirst('file://', ''))
    .toList();
});

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

文档更新日志

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

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

完善生命周期管理章节

---