webview_flutter_wkwebview 3.17.0使用指南

devtools/2025/2/2 4:49:56/

文档一

lib\inserted_web_seven\tell_to_ai\my_summary\webview_flutter_wkwebview_3.17.0_guide.txt

flutter_wkwebview3170__3">webview_flutter_wkwebview3.17.0 使用指南

日期：2025年1月26日

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

一、核心作用

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

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

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

二、典型应用场景

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

  1. 混合开发场景：
// 注册JS通信通道
controller.addJavaScriptChannel('Payment', (message) {handlePayment(message.message);
});
  1. 动态内容展示：
// 加载远程URL
controller.loadRequest(Uri.parse('https://news.example.com'));
  1. 企业应用集成：
// 设置Cookie认证
cookieManager.setCookie(WebViewCookie(name: 'auth_token',value: 'xxxx',domain: '.company.com'
));

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

三、关键配置参数

  1. 基础配置
WebKitWebViewControllerCreationParams(allowsInlineMediaPlayback: true,  // 内联媒体播放mediaTypesRequiringUserAction: {PlaybackMediaTypes.video} // 视频需交互
)
  1. 导航控制
controller.setNavigationDelegate(NavigationDelegate(onNavigationRequest: (request) => request.url.contains('ads') ? NavigationDecision.prevent : NavigationDecision.navigate
));
  1. 安全策略
// 证书校验（原生实现）
- (void)webView:(WKWebView *)webView didReceiveAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition, NSURLCredential *))handler {// 处理逻辑
}

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

四、标准工作流程

1:初始化控制器

2:配置参数

3:注册通信通道

4:设置导航代理

5:加载内容

6:处理交互

7:优化调试

流程图文本描述：

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

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

五、调试与优化

  1. 远程调试
if (kDebugMode) {WebViewController.setWebContentsDebuggingEnabled(true);
}
  1. 性能监控
final metrics = await controller.getPerformanceMetrics();
print('资源加载耗时: ${metrics[PerformanceMetric.resourceTiming]}');

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

六、注意事项

1必须启用混合渲染：

WebViewWidget(creationParams: WebKitWebViewWidgetCreationParams(displayWithHybridComposition: true)
)

2内存管理：

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

3文件上传适配方案：

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

三、关键配置参数

配置参数对比

1. 基础配置

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

2. 导航控制

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

3. 安全策略

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

4. 性能优化

参数名类型说明代码示例
cacheModeCacheMode缓存策略（noCache/loadElseNetwork 等）cacheMode: CacheMode.loadElseNetwork
preloadPagesList<String>预加载 URL 列表preloadPages: ['https://example.com/page1']

三、关键配置参数

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

四、典型应用流程
初始化控制器
配置参数
注册JS通信
设置导航代理
加载内容
处理交互
优化调试
  1. 初始化与配置
final controller = WebKitWebViewController()..setAllowsInlineMediaPlayback(true)..setMediaTypesRequiringUserAction({PlaybackMediaTypes.video});
  1. JavaScript 通信
// 注册 JS 通道
controller.addJavaScriptChannel('Scanner', (message) {final result = scanBarcode(); controller.evaluateJavascript('onScan("$result")');
});// 注入 JS 脚本
controller.injectJavascriptFile(assetPath: 'assets/custom.js',injectionTime: UserScriptInjectionTime.atDocumentStart
);
  1. 导航拦截
controller.setNavigationDelegate(NavigationDelegate(onNavigationRequest: (request) {if (request.url.contains('blocked-domain.com')) {return NavigationDecision.prevent;}return NavigationDecision.navigate;}
));
  1. 安全认证

// 原生层实现证书校验
- (void)webView:(WKWebView *)webView didReceiveAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition, NSURLCredential * _Nullable))completionHandler {if ([challenge.protectionSpace.authenticationMethod isEqualToString:NSURLAuthenticationMethodServerTrust]) {completionHandler(NSURLSessionAuthChallengeUseCredential, [NSURLCredential credentialForTrust:challenge.protectionSpace.serverTrust]);} else {completionHandler(NSURLSessionAuthChallengePerformDefaultHandling, nil);}
}
  1. 性能优化

// 配置缓存
controller.setCacheMode(cacheMode: CacheMode.loadElseNetwork,maxCacheSize: 200 * 1024 * 1024, // 200MB
);// 预加载关键资源
controller.loadRequest(Uri.parse('https://example.com/static/main.css'));
  1. 调试与监控

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

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


WebViewWidget(creationParams: WebKitWebViewWidgetCreationParams(displayWithHybridComposition: true,),
)

平台限制

iOS 11.0+ / macOS 10.13+ 强制使用 WKWebView

文件上传需处理 WKFileUploadPanel 的权限问题

内存管理
在 dispose() 中需手动释放资源：


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

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

文档二

lib\inserted_web_seven\tell_to_ai\my_summary\webview_flutter_wkwebview_3.17.0_docs.txt

flutter_wkwebview_3170__359">webview_flutter_wkwebview 3.17.0 技术文档

日期：2025年1月26日

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

一、核心类与接口

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

1. FWFWebViewFlutterWKWebViewExternalAPI :cite[1]

iOS 平台原生 API 访问入口类

◆ 功能说明：

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

◆ 构造函数：
Objective-C：

@import webview_flutter_wkwebview;
FWFWebViewFlutterWKWebViewExternalAPI *api = [FWFWebViewFlutterWKWebViewExternalAPI sharedInstance];

方法说明

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

◆ 关键方法：

方法签名	参数	返回值	功能描述
webViewForIdentifier:	NSNumber* (Flutter视图ID)	WKWebView*	根据 Flutter 视图ID获取对应的原生 WKWebView 实例
  1. WebKitWebViewControllerCreationParams
    iOS 平台 WebView 控制器配置参数

◆ 构造函数：

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

参数说明

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

◆ 参数说明：


参数名	                       类型	                    默认值	描述
allowsInlineMediaPlayback	    bool	                true	是否允许内联媒体播放
mediaTypesRequiringUserAction	Set<PlaybackMediaTypes>	空集合	需要用户交互的媒体类型
  1. WebKitWebViewController
    iOS 平台 WebView 核心控制器
    ◆ 构造函数：
WebKitWebViewController.fromPlatformCreationParams(WebKitWebViewControllerCreationParams params
)

◆ 主要方法：

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

主要方法对比

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

二、配置参数类型

  1. PlaybackMediaTypes 枚举
    控制需要用户交互的媒体类型

◆ 枚举值：

enum PlaybackMediaTypes {all,        // 所有媒体类型audio,      // 音频video,      // 视频
}
  1. WKUserScriptInjectionTime 映射
    JavaScript 注入时机（Dart 层与原生层映射）

◆ Dart 枚举：

enum UserScriptInjectionTime {atDocumentStart,   // 文档加载开始时注入atDocumentEnd,     // 文档加载结束时注入
}

◆ 对应原生枚举：

typedef NS_ENUM(NSInteger, WKUserScriptInjectionTime) {WKUserScriptInjectionTimeAtDocumentStart,WKUserScriptInjectionTimeAtDocumentEnd
};

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

三、原生交互接口

  1. JavaScript 通信协议
    ◆ 通道注册：
controller.addJavaScriptChannel('NativeBridge',onMessageReceived: (JavaScriptMessage message) {print('收到JS消息: ${message.message}');}
);

◆ 原生层实现：

// 对应 WKScriptMessageHandler 实现
- (void)userContentController:(WKUserContentController *)userContentController didReceiveScriptMessage:(WKScriptMessage *)message {[FWFWebViewFlutterWKWebViewExternalAPI.sharedInstancepostMessage:message.body forChannel:message.name];
}
  1. 导航拦截接口
    ◆ Dart 层配置：
controller.setNavigationDelegate(NavigationDelegate(onNavigationRequest: (request) {if (request.url.contains('blocked.com')) {return NavigationDecision.prevent;}return NavigationDecision.navigate;},
));

◆ 原生层映射：

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

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

四、平台特性配置

  1. 混合渲染模式
    iOS 平台强制使用 WKWebView 的混合合成模式

◆ 关键配置：

WebViewWidget(controller: controller,creationParams: WebKitWebViewWidgetCreationParams(displayWithHybridComposition: true,),
)
```dart
2. 安全策略 
◆ Cookie 管理：
```dart
final cookieManager = WebViewCookieManager();
await cookieManager.setCookie(WebViewCookie(name: 'session',value: '123',domain: 'example.com',path: '/',httpOnly: true,)
);

◆ 证书校验：
通过实现 WKNavigationDelegate 的
-webView:didReceiveAuthenticationChallenge:completionHandler: 方法

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

五、性能优化参数

  1. 缓存策略
controller.setCacheMode(cacheMode: CacheMode.loadElseNetwork,maxCacheSize: 100 * 1024 * 1024, // 100MB
);
  1. 资源预加载
controller.loadRequest(Uri.parse('https://example.com'),headers: {'Referer': 'https://mydomain.com'},
);

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

六、调试与监控

  1. 远程调试启用
if (kDebugMode) {await WebViewController.setWebContentsDebuggingEnabled(true);
}
  1. 性能指标采集
controller.enablePerformanceMetrics(metrics: {PerformanceMetric.navigationTiming,PerformanceMetric.resourceTiming,}
);

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

七、兼容性要求

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


http://www.ppmy.cn/devtools/155341.html

相关文章

2025美赛B题-问题B：管理可持续旅游

2025美赛B题-问题B：管理可持续旅游

美国阿拉斯加州朱诺市人口约 30,000人&#xff0c;2023 年创下160万邮轮乘客的纪录&#xff0c;在最繁忙的日子里&#xff0c;邮轮乘客多达7艘&#xff0c;游客人数超过 20,000人。1虽然这些游客为该市带来了约 3.75 亿美元的可观收入&#xff0c;!但也带来了与过度拥挤相关的问…
阅读更多...
Privacy Eraser，电脑隐私的终极清除者

Privacy Eraser，电脑隐私的终极清除者

Privacy Eraser 是一款专为保护用户隐私而设计的全能型软件&#xff0c;它不仅能够深度清理计算机中的各类隐私数据&#xff0c;还提供了多种系统优化工具&#xff0c;帮助用户提升设备的整体性能。通过这款软件&#xff0c;用户可以轻松清除浏览器历史记录、缓存文件、Cookie、…
阅读更多...
Python3 【装饰器】避坑指南：常见错误解析

Python3 【装饰器】避坑指南：常见错误解析

Python3 【装饰器】避坑指南&#xff1a;常见错误解析 在编写或使用 Python 装饰器时&#xff0c;可能会遇到一些典型的错误。以下是 15 种常见错误&#xff0c;分析出错原因并提供纠正方法&#xff0c;同时通过代码示例进行演示和说明。 1. 忘记调用被装饰的函数 错误原因&a…
阅读更多...
React Router v6配置路由守卫

React Router v6配置路由守卫

首先准备好以下页面 登录页&#xff1a;用户可以在此页面登录。 受保护页&#xff1a;只有登录的用户可以访问&#xff0c;否则会重定向到登录页。 公共页面&#xff1a;不需要鉴权&#xff0c;任何人都可以访问。 1. 安装依赖 首先&#xff0c;我们需要安装 react-router-do…
阅读更多...
Java算法——排序

Java算法——排序

目录 引言1. 插入排序1.1 基本思想1.2 直接插入排序1.3 希尔排序 2. 选择排序2.1 基本思想2.2 直接选择排序2.3 直接选择排序变种2.4 堆排序 3. 交换排序3.1 基本思想3.2 冒泡排序3.3 快速排序3.3.1 快速排序的基本结构3.3.2 Hoare法3.3.3 挖坑法3.3.4 双指针法 3.4 快速排序非…
阅读更多...
【ArcMap零基础训练营】02 MODIS数据的下载与处理

【ArcMap零基础训练营】02 MODIS数据的下载与处理

MODIS数据处理 230107直播录像 MODIS数据下载及处理 MODIS数据简介 中分辨率成像光谱仪&#xff08;The Moderate Resolution Imaging Spectroradiometer &#xff0c;MODIS&#xff09;是地球观测系统&#xff08;EOS&#xff09;Terra和Aqua平台上的一个关键仪器&#xff0c;…
阅读更多...
npm link 作用

npm link 作用

一、npm link 的定义 npm link 是 npm 提供的一个命令&#xff0c;它的主要作用是在本地开发 npm 包时&#xff0c;将本地开发的包链接到全局的 node_modules 目录中&#xff0c;并且在另一个项目中也可以使用这个本地开发的包&#xff0c;就好像它是一个通过 npm install 安装…
阅读更多...
Python 数据分析 - Matplotlib 绘图

Python 数据分析 - Matplotlib 绘图

Python 数据分析 - Matplotlib 绘图 简介绘图折线图单线多线子图 散点图直方图条形图纵置横置多条 饼图 简介 Matplotlib 是 Python 提供的一个绘图库&#xff0c;通过该库我们可以很容易的绘制出折线图、直方图、散点图、饼图等丰富的统计图&#xff0c;安装使用 pip install…
阅读更多...
最新文章

Copyright @ 2022~2023