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双向通讯
[*]安全计谋管理
[*]混合开发支持
==================================================
二、典型应用场景
==================================================
[*]混合开发场景：
// 注册JS通信通道
controller.addJavaScriptChannel('Payment', (message) {
handlePayment(message.message);
});
[*]动态内容展示：
// 加载远程URL
controller.loadRequest(Uri.parse('https://news.example.com'));
[*]企业应用集成：
// 设置Cookie认证
cookieManager.setCookie(WebViewCookie(
name: 'auth_token',
value: 'xxxx',
domain: '.company.com'
));
==================================================
三、关键配置参数
[*]基础配置
WebKitWebViewControllerCreationParams(
allowsInlineMediaPlayback: true,// 内联媒体播放
mediaTypesRequiringUserAction: {PlaybackMediaTypes.video} // 视频需交互
)
[*]导航控制
controller.setNavigationDelegate(NavigationDelegate(
onNavigationRequest: (request) =>
request.url.contains('ads')
? NavigationDecision.prevent
: NavigationDecision.navigate
));
[*]安全计谋
// 证书校验（原生实现）
- (void)webView:(WKWebView *)webView
didReceiveAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge
completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition, NSURLCredential *))handler {
// 处理逻辑
}
==================================================
四、标准工作流程
1:初始化控制器
2:配置参数
3:注册通讯通道
4:设置导航代理
5:加载内容
6:处理交互
7:优化调试
流程图文本描述：
初始化->配置->通信设置->加载内容->交互处理->性能优化
==================================================
五、调试与优化
[*]长途调试
if (kDebugMode) {
WebViewController.setWebContentsDebuggingEnabled(true);
}
[*]性能监控
final metrics = await controller.getPerformanceMetrics();
print('资源加载耗时: ${metrics}');
==================================================
六、留意事项
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: truemediaTypesRequiringUserActionSet<PlaybackMediaTypes>{}需用户交互的媒体类型（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. 基础配置
参数 类型 默认值 作用
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 列表
四、典型应用流程
[*]初始化与配置
final controller = WebKitWebViewController()
..setAllowsInlineMediaPlayback(true)
..setMediaTypesRequiringUserAction({PlaybackMediaTypes.video});
[*]JavaScript 通讯
// 注册 JS 通道
controller.addJavaScriptChannel('Scanner', (message) {
final result = scanBarcode();
controller.evaluateJavascript('onScan("$result")');
});
// 注入 JS 脚本
controller.injectJavascriptFile(
assetPath: 'assets/custom.js',
injectionTime: UserScriptInjectionTime.atDocumentStart
);
[*]导航拦截
controller.setNavigationDelegate(NavigationDelegate(
onNavigationRequest: (request) {
if (request.url.contains('blocked-domain.com')) {
return NavigationDecision.prevent;
}
return NavigationDecision.navigate;
}
));
[*]安全认证
// 原生层实现证书校验
- (void)webView:(WKWebView *)webView
didReceiveAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge
completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition, NSURLCredential * _Nullable))completionHandler {
if () {
completionHandler(NSURLSessionAuthChallengeUseCredential, );
} else {
completionHandler(NSURLSessionAuthChallengePerformDefaultHandling, nil);
}
}
[*]性能优化
// 配置缓存
controller.setCacheMode(
cacheMode: CacheMode.loadElseNetwork,
maxCacheSize: 200 * 1024 * 1024, // 200MB
);
// 预加载关键资源
controller.loadRequest(Uri.parse('https://example.com/static/main.css'));
[*]调试与监控
// 启用长途调试if (kDebugMode) {
WebViewController.setWebContentsDebuggingEnabled(true);
}
// 采集性能指标final metrics = await controller.getPerformanceMetrics();debugPrint('DOM加载耗时: ${metrics}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
webview_flutter_wkwebview 3.17.0 技术文档
日期：2025年1月26日
==================================================
一、核心类与接口
==================================================
1. FWFWebViewFlutterWKWebViewExternalAPI :cite
iOS 平台原生 API 访问入口类
◆ 功能阐明：
[*]提供对 WKWebView 原生层的直接访问
[*]用于混合开发场景下的原生代码扩展
◆ 构造函数：
Objective-C：
@import webview_flutter_wkwebview;
FWFWebViewFlutterWKWebViewExternalAPI *api = ;
方法阐明
方法签名参数类型返回值类型功能描述代码示例webViewForIdentifier:NSNumber*WKWebView*根据 Flutter 视图ID获取对应的原生 WKWebView 实例 ◆ 关键方法：
方法签名 参数 返回值 功能描述
webViewForIdentifier: NSNumber* (Flutter视图ID) WKWebView* 根据 Flutter 视图ID获取对应的原生 WKWebView 实例
[*]WebKitWebViewControllerCreationParams
iOS 平台 WebView 控制器配置参数
◆ 构造函数：
const WebKitWebViewControllerCreationParams({
bool allowsInlineMediaPlayback = true,
Set<PlaybackMediaTypes> mediaTypesRequiringUserAction = const {},
// 其他平台特有参数...
});
参数阐明
参数名类型默认值描述代码示例allowsInlineMediaPlaybackbooltrue是否允许内联媒体播放allowsInlineMediaPlayback: truemediaTypesRequiringUserActionSet<PlaybackMediaTypes>空聚集需要用户交互的媒体类型mediaTypesRequiringUserAction: {PlaybackMediaTypes.video} ◆ 参数阐明：
参数名 类型 默认值 描述
allowsInlineMediaPlayback bool true 是否允许内联媒体播放
mediaTypesRequiringUserAction Set<PlaybackMediaTypes> 空集合 需要用户交互的媒体类型
[*]WebKitWebViewController
iOS 平台 WebView 核心控制器
◆ 构造函数：
WebKitWebViewController.fromPlatformCreationParams(
WebKitWebViewControllerCreationParams params
)
◆ 主要方法：
方法签名 参数 功能描述
setUIDelegate WKUIDelegate 设置原生 WKUIDelegate
setNavigationDelegate WKNavigationDelegate 设置原生 WKNavigationDelegate
主要方法对比
方法签名参数类型功能描述代码示例setUIDelegateWKUIDelegate设置原生 WKUIDelegatecontroller.setUIDelegate(delegate)setNavigationDelegateWKNavigationDelegate设置原生 WKNavigationDelegatecontroller.setNavigationDelegate(delegate) 二、配置参数类型
[*]PlaybackMediaTypes 罗列
控制需要用户交互的媒体类型
◆ 罗列值：
enum PlaybackMediaTypes {
all, // 所有媒体类型
audio, // 音频
video, // 视频
}
[*]WKUserScriptInjectionTime 映射
JavaScript 注入时机（Dart 层与原生层映射）
◆ Dart 罗列：
enum UserScriptInjectionTime {
atDocumentStart, // 文档加载开始时注入
atDocumentEnd, // 文档加载结束时注入
}
◆ 对应原生罗列：
typedef NS_ENUM(NSInteger, WKUserScriptInjectionTime) {
WKUserScriptInjectionTimeAtDocumentStart,
WKUserScriptInjectionTimeAtDocumentEnd
};
==================================================
三、原生交互接口
[*]JavaScript 通讯协议
◆ 通道注册：
controller.addJavaScriptChannel(
'NativeBridge',
onMessageReceived: (JavaScriptMessage message) {
print('收到JS消息: ${message.message}');
}
);
◆ 原生层实现：
// 对应 WKScriptMessageHandler 实现
- (void)userContentController:(WKUserContentController *)userContentController
didReceiveScriptMessage:(WKScriptMessage *)message {
[FWFWebViewFlutterWKWebViewExternalAPI.sharedInstance
postMessage:message.body
forChannel:message.name];
}
[*]导航拦截接口
◆ Dart 层配置：
controller.setNavigationDelegate(NavigationDelegate(
onNavigationRequest: (request) {
if (request.url.contains('blocked.com')) {
return NavigationDecision.prevent;
}
return NavigationDecision.navigate;
},
));
◆ 原生层映射：
// 对应 WKNavigationDelegate 的
// -webView:decidePolicyForNavigationAction:decisionHandler: 实现
==================================================
四、平台特性配置
[*]混合渲染模式
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: 方法
==================================================
五、性能优化参数
[*]缓存计谋
controller.setCacheMode(
cacheMode: CacheMode.loadElseNetwork,
maxCacheSize: 100 * 1024 * 1024, // 100MB
);
[*]资源预加载
controller.loadRequest(
Uri.parse('https://example.com'),
headers: {'Referer': 'https://mydomain.com'},
);
==================================================
六、调试与监控
[*]长途调试启用
if (kDebugMode) {
await WebViewController.setWebContentsDebuggingEnabled(true);
}
[*]性能指标采集
controller.enablePerformanceMetrics(
metrics: {
PerformanceMetric.navigationTiming,
PerformanceMetric.resourceTiming,
}
);
==================================================
七、兼容性要求
平台 最低版本 保举版本 关键依赖
iOS 11.0 14.0+ WKWebView
macOS 10.13 12.0+ WKWebView
注：本包为 webview_flutter 的 iOS/macOS 平台实现，需配合主包利用
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。
页:
[1]