webview_flutter 4.10.0 技术文档

https://github.com/flutter/packages/tree/main/packages/webview_flutter/webview_flutter

文档一

webview_flutter_4.10.0_docs.txt
webview_flutter_4.10.0_docs.txt
webview_flutter_4.10.0_docs.txt

webview_flutter 4.10.0 技术文档

日期：2025年1月26日

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

一、核心类与接口

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

1. WebViewController

WebView 核心控制器，负责加载内容、配置参数及交互

dart 复制代码

// 构造函数
WebViewController.fromPlatformCreationParams(
  PlatformWebViewControllerCreationParams params
)


// 主要方法
1. loadRequest(Uri uri, {
   Map<String, String>? headers,
   Uint8List? body,
   LoadRequestMethod method = LoadRequestMethod.get
}) // 加载URL请求:cite[8]

2. setJavaScriptMode(JavaScriptMode mode) // 设置JS执行模式
3. addJavaScriptChannel(String name, {
   required void Function(JavaScriptMessage) onMessageReceived
}) // 注册JS通信通道:cite[4]
4. runJavaScript(String code) // 执行JS代码
5. runJavaScriptReturningResult(String code) // 执行JS并返回结果
6. setUserAgent(String? userAgent) // 设置User-Agent
7. clearCache() // 清理缓存（不包含本地存储）:cite[6]
// 平台扩展方法
if (controller.platform is AndroidWebViewController) {
  (controller.platform as AndroidWebViewController)
    .setMediaPlaybackRequiresUserGesture(false); // Android特有配置:cite[6]
}

WebViewWidget
用于渲染 WebView 的 Flutter Widget

dart 复制代码

// 构造函数
WebViewWidget({
required WebViewController controller,
Set<Factory<OneSequenceGestureRecognizer>>? gestureRecognizers
})

// 手势配置示例
gestureRecognizers: {
Factory<VerticalDragGestureRecognizer>(() => VerticalDragGestureRecognizer())
}

3. NavigationDelegate

导航事件处理委托

dart 复制代码

NavigationDelegate({
  NavigationRequestCallback? onNavigationRequest,
  PageEventCallback? onPageStarted,
  PageEventCallback? onPageFinished,
  ProgressCallback? onProgress,
  WebResourceErrorCallback? onWebResourceError
})

// 拦截示例
onNavigationRequest: (request) {
  if (request.url.contains('blocked.com')) {
    return NavigationDecision.prevent;
  }
  return NavigationDecision.navigate;
}:cite[4]:cite[10]

WebViewCookieManager
Cookie 管理工具

dart 复制代码

final cookieManager = WebViewCookieManager();
await cookieManager.setCookie(
WebViewCookie(
name: 'session',
value: '123',
domain: 'example.com',
path: '/',
httpOnly: true
)
)

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

二、配置参数与枚举类型

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

1. JavaScriptMode 枚举

dart 复制代码

enum JavaScriptMode {
  disabled,   // 禁用JS执行
  unrestricted // 允许JS完全执行:cite[10]
}

CacheMode 枚举

dart 复制代码

enum CacheMode {
loadDefault, // 默认缓存策略
loadNoCache, // 跳过缓存
loadElseNetwork, // 优先使用缓存
loadCacheElseNetwork
}

3. PlaybackMediaTypes 枚举（iOS/macOS）

dart 复制代码

enum PlaybackMediaTypes {
  all,    // 所有媒体类型
  audio,  // 音频
  video   // 视频
}:cite[6]

WebResourceError 类

dart 复制代码

class WebResourceError {
final int errorCode;
final String description;
final bool isForMainFrame; // 是否主框架错误7
}

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

三、平台特定配置

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

1. Android 配置

dart 复制代码

// 初始化参数
AndroidWebViewControllerCreationParams(
  displayWithHybridComposition: true, // 强制混合渲染模式
  enableDebugging: true               // 启用调试模式
)

// 启用Material组件
if (Platform.isAndroid) {
  WebView.platform = SurfaceAndroidWebView();
}:cite[3]:cite[6]

iOS/macOS 配置

dart 复制代码

WebKitWebViewControllerCreationParams(
allowsInlineMediaPlayback: true, // 内联媒体播放
mediaTypesRequiringUserAction: {PlaybackMediaTypes.video}
)

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

四、交互与通信

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

1. Flutter 调用 JS

dart 复制代码

// 执行简单JS
controller.runJavaScript('alert("Hello")');

// 获取JS返回值
final height = await controller.runJavaScriptReturningResult(
  'document.body.scrollHeight'
) as int;:cite[8]

JS 调用 Flutter

dart 复制代码

// 注册通道
controller.addJavaScriptChannel('Bridge', (message) {
print('收到JS消息: ${message.message}');
});

// JS调用方式
window.Bridge.postMessage('Hello from JS');

3. 页面高度自适应

dart 复制代码

// 注入ResizeObserver监听
controller.runJavaScript('''
  new ResizeObserver(entries => 
    Report.postMessage(document.body.scrollHeight)
  ).observe(document.body)
''');

// Dart端接收
controller.addJavaScriptChannel('Report', (message) {
  setState(() => height = double.parse(message.message));
}):cite[4]

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

五、高级功能

POST请求

dart 复制代码

controller.loadRequest(
Uri.parse('https://api.example.com'),
method: LoadRequestMethod.post,
body: Uint8List.fromList(utf8.encode('data')),
headers: {'Content-Type': 'application/json'}
)

2. 本地HTML加载

dart 复制代码

// 加载Assets文件
controller.loadFlutterAsset('assets/page.html');

// 加载字符串
controller.loadHtmlString('<h1>Local Content</h1>',
  baseUrl: 'https://base.example.com'):cite[8]

滚动控制

dart 复制代码

// 获取滚动位置
final position = await controller.getScrollPosition();

// 滚动到指定位置
controller.scrollTo(0, 500);

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

六、迁移指南（3.x → 4.x）

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

WebView 类已废弃，拆分为：
- WebViewController：控制逻辑
- WebViewWidget：渲染组件:cite[6]
方法变更：
- evaluateJavascript → runJavaScriptReturningResult
- loadUrl → loadRequest
- clearCache 不再清理本地存储:cite[6]
导航委托迁移：

dart 复制代码

   // 旧版
   WebView(navigationDelegate: ...)
   
   // 新版
   controller.setNavigationDelegate(...):cite[6]

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

七、调试与优化

启用Android调试：

dart AndroidWebViewController.enableDebugging(true);:cite[6]

性能监控：

dart controller.enablePerformanceMetrics( metrics: {PerformanceMetric.resourceTiming} ):cite[6]

缓存策略：

dart controller.setCacheMode( cacheMode: CacheMode.loadElseNetwork, maxCacheSize: 100 * 1024 * 1024 // 100MB ):cite[6]

注：实际开发需根据目标平台导入对应实现包：

yaml 复制代码

dependencies:
  webview_flutter: ^4.10.0
  webview_flutter_android: ^4.3.0   # Android 扩展
  webview_flutter_wkwebview: ^3.17.0 # iOS/macOS 扩展:cite[6]

文档二

D:\F\lvjun\lib\inserted_web_seven\tell_to_ai\my_summary\webview_flutter_4.10.0_guide.txt

webview_flutter_4.10.0_guide.txt

一、核心作用

webview_flutter 是 Flutter 官方提供的跨平台 WebView 组件，用于在移动应用中嵌入网页内容。其核心功能包括：

多平台支持：基于 Android WebView / iOS WKWebView 实现

双向通信：支持 JavaScript 与 Flutter 的交互

导航控制：拦截处理页面跳转请求

媒体支持：内联视频播放、自动媒体加载策略

安全策略：Cookie 管理、HTTPS 证书校验

二、典型应用场景对比

场景类型	具体案例	技术实现要点
内嵌浏览器	应用内置网页浏览器	`导航控制`、`手势支持`
动态内容展示	商品详情页/新闻页	`远程URL加载`、`缓存优化`
混合开发	Flutter+Web 混合应用	`JS通信`、`本地HTML加载`
第三方集成	支付/地图/客服系统	`安全域限制`、`POST请求`
企业应用	OA 系统/数据看板	`Cookie认证`、`HTTPS强制`

二、典型应用场景

c 复制代码

场景类型	    具体案例	           技术实现要点
内嵌浏览器	    应用内置网页浏览器	   导航控制、手势支持
动态内容展示	商品详情页/新闻页	   远程 URL 加载、缓存优化
混合开发	    Flutter+Web 混合应用  JS 通信、本地 HTML 加载
第三方服务集成	支付/地图/客服系统	   安全域限制、POST 请求
企业应用	    OA 系统/数据看板	  Cookie 认证、HTTPS 强制

三、关键配置参数对比

1. 基础配置

参数	作用/说明	注意事项
`javascriptMode`	启用/禁用 JS 执行	需设置 `unrestricted` 启用复杂交互
`userAgent`	自定义浏览器标识	需适配目标网站 UA 检测规则
`gestureRecognizers`	自定义手势识别	需处理与 Flutter 手势的冲突

2. 导航控制

参数	作用/说明	注意事项
`onNavigationRequest`	拦截处理页面跳转请求	需返回 `NavigationDecision` 枚举值
`onPageFinished`	页面加载完成事件监听	适合注入 JS 脚本或统计加载耗时

3. 性能优化

参数	作用/说明	注意事项
`cacheMode`	定义资源缓存策略	推荐 `loadElseNetwork` 平衡性能
`preloadPages`	预加载指定 URL 页面	需控制数量避免内存过高
`enablePerformanceMetrics`	启用性能指标采集	需选择关键指标避免性能开销

三、关键配置参数

c 复制代码

1. 基础配置
参数	            类型	          默认值	 作用
javascriptMode	    JavaScriptMode	 disabled	启用/禁用 JS 执行
userAgent	        String?	         系统默认	 自定义浏览器标识
gestureRecognizers	Set<Factory>	 null	     自定义手势识别
2. 导航控制
参数	             类型	                  说明
onNavigationRequest	NavigationDecision       Function(NavigationRequest)	导航拦截回调
onPageFinished	   void Function(String)	 页面加载完成回调
3. 性能优化
参数	                   类型              	    说明
cacheMode	              CacheMode	                缓存策略（loadElseNetwork 等）
preloadPages	          List<String>	            预加载 URL 列表
enablePerformanceMetrics	Set<PerformanceMetric>	性能指标采集

平台差异配置
Android 特有：

dart 复制代码

AndroidWebViewControllerCreationParams(
  displayWithHybridComposition: true, // 必须启用
  enableDebugging: kDebugMode,        // 调试模式
)

iOS 特有：

dart 复制代码

WebKitWebViewControllerCreationParams(
  allowsInlineMediaPlayback: true,
  mediaTypesRequiringUserAction: {PlaybackMediaTypes.video}
)

四、标准使用流程
初始化控制器配置基础参数注册JS通信设置导航代理加载内容处理交互事件性能优化资源释放

初始化与配置

dart 复制代码

final controller = WebViewController()
  ..setJavaScriptMode(JavaScriptMode.unrestricted)
  ..setUserAgent('MyApp/1.0')
  ..setNavigationDelegate(NavigationDelegate(
    onNavigationRequest: (request) => _handleNavigation(request)
  ));

内容加载示例

dart 复制代码

// 加载远程URL
controller.loadRequest(Uri.parse('https://example.com'));

// 加载本地HTML
controller.loadHtmlString('''
  <html><body><h1>Local Content</h1></body></html>
''', baseUrl: 'https://base.example.com');

交互处理

dart 复制代码

// 注册JS通道
controller.addJavaScriptChannel('Scanner', (message) {
  final result = scanBarcode();
  controller.runJavaScript('onScanResult("$result")');
});

// 处理支付回调
controller.setNavigationDelegate(NavigationDelegate(
  onNavigationRequest: (request) {
    if (request.url.startsWith('alipay://')) {
      _handlePayment(request.url);
      return NavigationDecision.prevent;
    }
    return NavigationDecision.navigate;
  }
));

性能优化

dart 复制代码

// 设置缓存策略
controller.setCacheMode(
  cacheMode: CacheMode.loadElseNetwork,
  maxCacheSize: 200 * 1024 * 1024, // 200MB
);

// 启用性能监控
controller.enablePerformanceMetrics(
  metrics: {PerformanceMetric.resourceTiming}
);

五、注意事项

1.混合渲染模式

Android 必须启用混合渲染以避免白屏：

dart 复制代码

WebViewWidget(
  creationParams: AndroidWebViewCreationParams(
    displayWithHybridComposition: true
  )
)

2.内存管理

在页面销毁时需手动释放资源：

dart 复制代码

@override
void dispose() {
  controller.dispose();
  super.dispose();
}

3.平台差异处理

iOS 文件上传：需实现 WKFileUploadPanelDelegate
Android 证书校验：通过 WebViewClient.onReceivedSslError 处理

4.调试工具

dart 复制代码

// 启用远程调试
if (kDebugMode) {
  WebViewController.setWebContentsDebuggingEnabled(true);
}

此总结涵盖了该包的核心使用要点，实际开发时建议参考官方文档获取最新 API 变更信息。对于复杂场景（如 WebRTC 支持），需结合平台原生代码扩展实现。

webview_flutter 4.10.0 完整使用指南

日期：2025年1月26日

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

一、初始化控制器

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

dart 复制代码

// 在 StatefulWidget 中初始化
late final WebViewController controller;

@override
void initState() {
  super.initState();
  controller = WebViewController();
}

注意：

必须使用 late 延迟初始化
建议在 initState 中创建实例

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

二、配置基础参数

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

dart 复制代码

controller
  ..setJavaScriptMode(JavaScriptMode.unrestricted)
  ..setUserAgent('MyApp/1.0')
  ..setBackgroundColor(Colors.transparent)
  ..setNavigationDelegate(NavigationDelegate(
    onNavigationRequest: _handleNavigation
  ));

关键配置说明：

JavaScriptMode.unrestricted: 完全启用JS
UserAgent: 用于伪装浏览器环境
透明背景: 避免页面加载时的白屏闪烁

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

三、注册JS通信

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

dart 复制代码

// Flutter端注册通道
controller.addJavaScriptChannel(
  'Scanner',
  onMessageReceived: (JavaScriptMessage message) {
    final result = scanBarcode();
    controller.runJavaScript('onScanResult("$result")');
  }
);

// JS调用示例（网页中）：
// window.Scanner.postMessage('start');

通道规范：

通道名称需全平台统一
复杂数据建议使用JSON格式

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

四、设置导航代理

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

dart 复制代码

NavigationDelegate _buildDelegate() {
  return NavigationDelegate(
    onNavigationRequest: (request) {
      if (request.url.contains('ads')) {
        return NavigationDecision.prevent;
      }
      return NavigationDecision.navigate;
    },
    onPageFinished: (url) {
      controller.runJavaScript('initPage()');
    }
  );
}

拦截策略：

阻止广告域名
加载完成后注入初始化脚本

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

五、加载内容

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

dart 复制代码

// 加载远程URL（带自定义Header）
controller.loadRequest(
  Uri.parse('https://api.example.com'),
  headers: {'Authorization': 'Bearer xxx'},
  method: LoadRequestMethod.post
);

// 加载本地HTML
controller.loadHtmlString('''
  <html>
    <body>Local Content</body>
    <script>
      window.Scanner.postMessage('ready');
    </script>
  </html>
''');

加载方式对比：

方法	适用场景	注意事项
loadRequest	常规网页加载	支持GET/POST
loadHtmlString	动态内容生成	必须设置baseUrl
loadFlutterAsset	打包的本地HTML文件	需在pubspec.yaml声明

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

六、处理交互事件

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

dart 复制代码

// 手势冲突处理
WebViewWidget(
  controller: controller,
  gestureRecognizers: {
    Factory<VerticalDragGestureRecognizer>(
      () => VerticalDragGestureRecognizer()
    )
  }
)

// 处理支付回调
controller.setNavigationDelegate(NavigationDelegate(
  onUrlChange: (url) {
    if (url?.scheme == 'alipay') {
      _handlePayment(url!);
    }
  }
));

典型交互场景：

页面滚动与Flutter列表滑动冲突
第三方支付协议处理
文件上传适配

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

七、性能优化

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

dart 复制代码

// 设置缓存策略
controller.setCacheMode(
  cacheMode: CacheMode.loadElseNetwork,
  maxCacheSize: 200 * 1024 * 1024, // 200MB
);

// 预加载关键资源
controller.loadRequest(Uri.parse('https://example.com/static/main.css'));

// 监控性能指标
final metrics = await controller.getPerformanceMetrics();
print('DOM加载耗时: ${metrics['domContentLoaded']}ms');

优化策略：

优先缓存静态资源
按需预加载下一页内容
定期清理过期缓存

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

八、资源释放

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

dart 复制代码

@override
void dispose() {
  controller.clearCache(); // 可选清理缓存
  controller.dispose();    // 必须释放控制器
  super.dispose();
}

释放场景：

页面关闭时
用户登出时
切换账号时

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

九、完整示例代码

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

dart 复制代码

import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';

class WebViewPage extends StatefulWidget {
  const WebViewPage({super.key});

  @override
  State<WebViewPage> createState() => _WebViewPageState();
}

class _WebViewPageState extends State<WebViewPage> {
  late final WebViewController controller;

  @override
  void initState() {
    super.initState();
    controller = WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..addJavaScriptChannel('Bridge', onMessageReceived: _handleMessage)
      ..setNavigationDelegate(_buildDelegate())
      ..loadRequest(Uri.parse('https://example.com'));
  }

  NavigationDelegate _buildDelegate() {
    return NavigationDelegate(
      onNavigationRequest: (request) {
        return request.url.contains('ads') 
          ? NavigationDecision.prevent 
          : NavigationDecision.navigate;
      }
    );
  }

  void _handleMessage(JavaScriptMessage message) {
    print('Received: ${message.message}');
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('WebView Demo')),
      body: WebViewWidget(controller: controller),
    );
  }

  @override
  void dispose() {
    controller.dispose();
    super.dispose();
  }
}

复制代码