webview_flutter_wkwebview 3.17.0利用指南

文档一

lib\inserted_web_seven\tell_to_ai\my_summary\webview_flutter_wkwebview_3.17.0_guide.txt
webview_flutter_wkwebview3.17.0 利用指南

日期：2025年1月26日

==================================================
一、核心作用

==================================================
iOS/macOS平台的Flutter WebView实现组件，基于WKWebView提供：

• 高性能网页渲染
  
• 原生与Web双向通讯
  
• 安全计谋管理
  
• 混合开发支持
  

==================================================
二、典型应用场景

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

• 混合开发场景：
  

1. // 注册JS通信通道
2. controller.addJavaScriptChannel('Payment', (message) {
3.   handlePayment(message.message);
4. });

复制代码

• 动态内容展示：
  

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

复制代码

• 企业应用集成：
  

1. // 设置Cookie认证
2. cookieManager.setCookie(WebViewCookie(
3.   name: 'auth_token',
4.   value: 'xxxx',
5.   domain: '.company.com'
6. ));

复制代码

==================================================
三、关键配置参数

• 基础配置
  

1. WebKitWebViewControllerCreationParams(
2.   allowsInlineMediaPlayback: true,  // 内联媒体播放
3.   mediaTypesRequiringUserAction: {PlaybackMediaTypes.video} // 视频需交互
4. )

复制代码

• 导航控制
  

1. controller.setNavigationDelegate(NavigationDelegate(
2.   onNavigationRequest: (request) =>
3.     request.url.contains('ads')
4.       ? NavigationDecision.prevent
5.       : NavigationDecision.navigate
6. ));

复制代码

• 安全计谋
  

1. // 证书校验（原生实现）
2. - (void)webView:(WKWebView *)webView
3.   didReceiveAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge
4.   completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition, NSURLCredential *))handler {
5.   // 处理逻辑
6. }

复制代码

==================================================
四、标准工作流程

1:初始化控制器
2:配置参数
3:注册通讯通道
4:设置导航代理
5:加载内容
6:处理交互
7:优化调试
流程图文本描述：

1. 初始化->配置->通信设置->加载内容->交互处理->性能优化

复制代码

==================================================
五、调试与优化

• 长途调试
  

1. if (kDebugMode) {
2.   WebViewController.setWebContentsDebuggingEnabled(true);
3. }

复制代码

• 性能监控
  

1. final metrics = await controller.getPerformanceMetrics();
2. print('资源加载耗时: ${metrics[PerformanceMetric.resourceTiming]}');

复制代码

==================================================
六、留意事项

1必须启用混合渲染：

1. WebViewWidget(
2.   creationParams: WebKitWebViewWidgetCreationParams(
3.     displayWithHybridComposition: true
4.   )
5. )

复制代码

2内存管理：

1. @override
2. void dispose() {
3.   controller.dispose();
4.   super.dispose();
5. }

复制代码

3文件上传适配方案：

1. // 实现WKFileUploadPanelDelegate协议处理iOS文件选择

复制代码

==================================================
一、核心作用
webview_flutter_wkwebview 是 Flutter 官方提供的 iOS/macOS 平台 WebView 实现插件，基于苹果的 WKWebView 组件，用于在 Flutter 应用中嵌入高性能、安全的网页渲染容器。主要功能包括：
加载本地或长途 HTML/CSS/JavaScript 内容
支持现代 Web 标准（如 WebGL、WebAssembly）
提供原生与 Web 的双向通讯本事
实现页面导航控制、缓存管理、安全计谋等
适用场景对比

场景类型详细案例技术需求代码示例混合开发应用中嵌入第三方支付页面、舆图服务JavaScript 通讯、导航拦截controller.addJavaScriptChannel('Payment', onMessageReceived)动态内容展示实时更新的新闻/商品详情页长途 URL 加载、缓存优化controller.loadRequest(Uri.parse('https://example.com'))企业应用内网 OA 系统、数据可视化大屏Cookie 认证、安全计谋cookieManager.setCookie(WebViewCookie(...))跨平台组件复用已有的 Web 前端组件（如视频播放器）内联媒体播放、手势支持allowsInlineMediaPlayback: true调试工具应用内 Web 开发者工具长途调试、性能监控WebViewController.setWebContentsDebuggingEnabled(true)

1. 二、适用场景
3. 场景类型            具体案例                                     技术需求
4. 混合开发            应用中嵌入第三方支付页面、地图服务             JavaScript 通信、导航拦截
5. 动态内容            展示实时更新的新闻/商品详情页                 远程 URL 加载、缓存优化
6. 企业应用            内网 OA 系统、数据可视化大屏                 Cookie 认证、安全策略
7. 跨平台组件        复用已有的 Web 前端组件（如视频播放器）         内联媒体播放、手势支持
8. 调试工具            应用内 Web 开发者工具                         远程调试、性能监控

复制代码

三、关键配置参数
配置参数对比

1. 基础配置

参数名类型默认值作用代码示例allowsInlineMediaPlaybackbooltrue允许视频内联播放（非全屏）allowsInlineMediaPlayback: truemediaTypesRequiringUserActionSet<laybackMediaTypes>{}需用户交互的媒体类型（audio/video/all）mediaTypesRequiringUserAction: {PlaybackMediaTypes.video} 2. 导航控制

参数名类型阐明代码示例allowsBackForwardNavigationGesturesbool启用/禁用左右滑动手势导航allowsBackForwardNavigationGestures: truenavigationDelegateNavigationDelegate拦截处理页面跳转请求controller.setNavigationDelegate(delegate) 3. 安全计谋

参数名类型功能代码示例contentModeWKContentMode移动端/桌面端渲染模式contentMode: WKContentMode.mobilecredentialURLCredentialHTTPS 证书认证配置credential: URLCredential(...) 4. 性能优化

参数名类型阐明代码示例cacheModeCacheMode缓存计谋（noCache/loadElseNetwork 等）cacheMode: CacheMode.loadElseNetworkpreloadPagesList<String>预加载 URL 列表preloadPages: ['https://example.com/page1'] 三、关键配置参数

1. 1. 基础配置
2. 参数                                    类型                          默认值        作用
3. allowsInlineMediaPlayback            bool                       true        允许视频内联播放（非全屏）
4. mediaTypesRequiringUserAction        Set<PlaybackMediaTypes>        {}        需用户交互的媒体类型（audio/video/all）
5. 2. 导航控制
6. 参数                                          类型                      说明
7. allowsBackForwardNavigationGestures          bool                      启用/禁用左右滑动手势导航
8. navigationDelegate                          NavigationDelegate  拦截处理页面跳转请求
9. 3. 安全策略
10. 参数        类型        功能
11. contentMode        WKContentMode        移动端/桌面端渲染模式
12. credential        URLCredential        HTTPS 证书认证配置
13. 4. 性能优化
14. 参数        类型        说明
15. cacheMode            CacheMode            缓存策略（noCache/loadElseNetwork 等）
16. preloadPages        List<String>        预加载 URL 列表

复制代码

四、典型应用流程
     

• 初始化与配置
  

1. final controller = WebKitWebViewController()
2.   ..setAllowsInlineMediaPlayback(true)
3.   ..setMediaTypesRequiringUserAction({PlaybackMediaTypes.video});

复制代码

• JavaScript 通讯
  

1. // 注册 JS 通道
2. controller.addJavaScriptChannel('Scanner', (message) {
3.   final result = scanBarcode();
4.   controller.evaluateJavascript('onScan("$result")');
5. });
7. // 注入 JS 脚本
8. controller.injectJavascriptFile(
9.   assetPath: 'assets/custom.js',
10.   injectionTime: UserScriptInjectionTime.atDocumentStart
11. );

复制代码

• 导航拦截
  

1. controller.setNavigationDelegate(NavigationDelegate(
2.   onNavigationRequest: (request) {
3.     if (request.url.contains('blocked-domain.com')) {
4.       return NavigationDecision.prevent;
5.     }
6.     return NavigationDecision.navigate;
7.   }
8. ));

复制代码

• 安全认证
  

2. // 原生层实现证书校验
3. - (void)webView:(WKWebView *)webView
4.   didReceiveAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge
5.   completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition, NSURLCredential * _Nullable))completionHandler {
6.   
7.   if ([challenge.protectionSpace.authenticationMethod isEqualToString:NSURLAuthenticationMethodServerTrust]) {
8.     completionHandler(NSURLSessionAuthChallengeUseCredential, [NSURLCredential credentialForTrust:challenge.protectionSpace.serverTrust]);
9.   } else {
10.     completionHandler(NSURLSessionAuthChallengePerformDefaultHandling, nil);
11.   }
12. }

复制代码

• 性能优化
  

2. // 配置缓存
3. controller.setCacheMode(
4.   cacheMode: CacheMode.loadElseNetwork,
5.   maxCacheSize: 200 * 1024 * 1024, // 200MB
6. );
8. // 预加载关键资源
9. controller.loadRequest(Uri.parse('https://example.com/static/main.css'));

复制代码

• 调试与监控
  

1. // 启用长途调试if (kDebugMode) {
2.   WebViewController.setWebContentsDebuggingEnabled(true);
3. }
4. // 采集性能指标final metrics = await controller.getPerformanceMetrics();debugPrint('DOM加载耗时: ${metrics[PerformanceMetric.domContentLoaded]}ms');

复制代码

五、留意事项
混合渲染模式
必须设置 displayWithHybridComposition: true 以避免 iOS 15+ 的渲染异常：

2. WebViewWidget(
3.   creationParams: WebKitWebViewWidgetCreationParams(
4.     displayWithHybridComposition: true,
5.   ),
6. )

复制代码

平台限制
iOS 11.0+ / macOS 10.13+ 强制利用 WKWebView
文件上传需处理 WKFileUploadPanel 的权限问题
内存管理
在 dispose() 中需手动开释资源：

2. @override
3. void dispose() {
4.   controller.clearCache();
5.   controller.dispose();
6.   super.dispose();
7. }

复制代码

此总结涵盖了该包的核心功能、配置要点及实际开发中的关键流程，可作为快速集成参考。
文档二

lib\inserted_web_seven\tell_to_ai\my_summary\webview_flutter_wkwebview_3.17.0_docs.txt
webview_flutter_wkwebview 3.17.0 技术文档

日期：2025年1月26日

==================================================
一、核心类与接口

==================================================
1. FWFWebViewFlutterWKWebViewExternalAPI :cite[1]

iOS 平台原生 API 访问入口类
◆ 功能阐明：

• 提供对 WKWebView 原生层的直接访问
  
• 用于混合开发场景下的原生代码扩展
  

◆ 构造函数：
Objective-C：

1. @import webview_flutter_wkwebview;
2. FWFWebViewFlutterWKWebViewExternalAPI *api = [FWFWebViewFlutterWKWebViewExternalAPI sharedInstance];

复制代码

方法阐明

方法签名参数类型返回值类型功能描述代码示例webViewForIdentifier:NSNumber*WKWebView*根据 Flutter 视图ID获取对应的原生 WKWebView 实例[api webViewForIdentifier(viewId)] ◆ 关键方法：

1. 方法签名        参数        返回值        功能描述
2. webViewForIdentifier:        NSNumber* (Flutter视图ID)        WKWebView*        根据 Flutter 视图ID获取对应的原生 WKWebView 实例

复制代码

• WebKitWebViewControllerCreationParams
  iOS 平台 WebView 控制器配置参数
  

◆ 构造函数：

1. const WebKitWebViewControllerCreationParams({
2.   bool allowsInlineMediaPlayback = true,
3.   Set<PlaybackMediaTypes> mediaTypesRequiringUserAction = const {},
4.   // 其他平台特有参数...
5. });

复制代码

参数阐明

参数名类型默认值描述代码示例allowsInlineMediaPlaybackbooltrue是否允许内联媒体播放allowsInlineMediaPlayback: truemediaTypesRequiringUserActionSet<laybackMediaTypes>空聚集需要用户交互的媒体类型mediaTypesRequiringUserAction: {PlaybackMediaTypes.video} ◆ 参数阐明：

2. 参数名                               类型                            默认值        描述
3. allowsInlineMediaPlayback            bool                        true        是否允许内联媒体播放
4. mediaTypesRequiringUserAction        Set<PlaybackMediaTypes>        空集合        需要用户交互的媒体类型

复制代码

• WebKitWebViewController
  iOS 平台 WebView 核心控制器
  ◆ 构造函数：
  

1. WebKitWebViewController.fromPlatformCreationParams(
2.   WebKitWebViewControllerCreationParams params
3. )

复制代码

◆ 主要方法：

1. 方法签名                           参数                        功能描述
2. setUIDelegate                 WKUIDelegate                设置原生 WKUIDelegate
3. setNavigationDelegate        WKNavigationDelegate        设置原生 WKNavigationDelegate

复制代码

主要方法对比

方法签名参数类型功能描述代码示例setUIDelegateWKUIDelegate设置原生 WKUIDelegatecontroller.setUIDelegate(delegate)setNavigationDelegateWKNavigationDelegate设置原生 WKNavigationDelegatecontroller.setNavigationDelegate(delegate) 二、配置参数类型

• PlaybackMediaTypes 罗列
  控制需要用户交互的媒体类型
  

◆ 罗列值：

1. enum PlaybackMediaTypes {
2.   all,        // 所有媒体类型
3.   audio,      // 音频
4.   video,      // 视频
5. }

复制代码

• WKUserScriptInjectionTime 映射
  JavaScript 注入时机（Dart 层与原生层映射）
  

◆ Dart 罗列：

1. enum UserScriptInjectionTime {
2.   atDocumentStart,   // 文档加载开始时注入
3.   atDocumentEnd,     // 文档加载结束时注入
4. }

复制代码

◆ 对应原生罗列：

1. typedef NS_ENUM(NSInteger, WKUserScriptInjectionTime) {
2.   WKUserScriptInjectionTimeAtDocumentStart,
3.   WKUserScriptInjectionTimeAtDocumentEnd
4. };

复制代码

==================================================
三、原生交互接口

• JavaScript 通讯协议
  ◆ 通道注册：
  

1. controller.addJavaScriptChannel(
2.   'NativeBridge',
3.   onMessageReceived: (JavaScriptMessage message) {
4.     print('收到JS消息: ${message.message}');
5.   }
6. );

复制代码

◆ 原生层实现：

1. // 对应 WKScriptMessageHandler 实现
2. - (void)userContentController:(WKUserContentController *)userContentController
3.       didReceiveScriptMessage:(WKScriptMessage *)message {
4.   [FWFWebViewFlutterWKWebViewExternalAPI.sharedInstance
5.     postMessage:message.body
6.     forChannel:message.name];
7. }

复制代码

• 导航拦截接口
  ◆ Dart 层配置：
  

1. controller.setNavigationDelegate(NavigationDelegate(
2.   onNavigationRequest: (request) {
3.     if (request.url.contains('blocked.com')) {
4.       return NavigationDecision.prevent;
5.     }
6.     return NavigationDecision.navigate;
7.   },
8. ));

复制代码

◆ 原生层映射：

1. // 对应 WKNavigationDelegate 的
2. // -webView:decidePolicyForNavigationAction:decisionHandler: 实现

复制代码

==================================================
四、平台特性配置

• 混合渲染模式
  iOS 平台强制利用 WKWebView 的混合合成模式
  

◆ 关键配置：

1. WebViewWidget(
2.   controller: controller,
3.   creationParams: WebKitWebViewWidgetCreationParams(
4.     displayWithHybridComposition: true,
5.   ),
6. )
7. ```dart
8. 2. 安全策略
9. ◆ Cookie 管理：
10. ```dart
11. final cookieManager = WebViewCookieManager();
12. await cookieManager.setCookie(
13.   WebViewCookie(
14.     name: 'session',
15.     value: '123',
16.     domain: 'example.com',
17.     path: '/',
18.     httpOnly: true,
19.   )
20. );

复制代码

◆ 证书校验：
通过实现 WKNavigationDelegate 的
-webView:didReceiveAuthenticationChallenge:completionHandler: 方法
==================================================
五、性能优化参数

• 缓存计谋
  

1. controller.setCacheMode(
2.   cacheMode: CacheMode.loadElseNetwork,
3.   maxCacheSize: 100 * 1024 * 1024, // 100MB
4. );

复制代码

• 资源预加载
  

1. controller.loadRequest(
2.   Uri.parse('https://example.com'),
3.   headers: {'Referer': 'https://mydomain.com'},
4. );

复制代码

==================================================
六、调试与监控

• 长途调试启用
  

1. if (kDebugMode) {
2.   await WebViewController.setWebContentsDebuggingEnabled(true);
3. }

复制代码

• 性能指标采集
  

1. controller.enablePerformanceMetrics(
2.   metrics: {
3.     PerformanceMetric.navigationTiming,
4.     PerformanceMetric.resourceTiming,
5.   }
6. );

复制代码

==================================================
七、兼容性要求

平台 最低版本 保举版本 关键依赖
iOS 11.0 14.0+ WKWebView
macOS 10.13 12.0+ WKWebView
注：本包为 webview_flutter 的 iOS/macOS 平台实现，需配合主包利用

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。