跳转到内容
WebView AllWebView All
这是 1.4.x 版本的文档,最新接口请切换至 latest。

iOS 和 macOS

iOS 和 macOS 由 webview_all_wkwebview '>=1.4.12 <1.5.0' 提供。

项值
平台包webview_all_wkwebview
ControllerWebKitWebViewController
WidgetWebKitWebViewWidget
DelegateWebKitNavigationDelegate
Cookie managerWebKitWebViewCookieManager
引擎WKWebView
最低 iOS13.0+
最低 macOS10.15+
final params = WebKitWebViewControllerCreationParams(
allowsInlineMediaPlayback: true,
mediaTypesRequiringUserAction: const <PlaybackMediaTypes>{},
limitsNavigationsToAppBoundDomains: false,
javaScriptCanOpenWindowsAutomatically: true,
);
参数作用
mediaTypesRequiringUserAction哪些媒体类型需要用户手势。
allowsInlineMediaPlayback允许 HTML5 视频内联播放。
limitsNavigationsToAppBoundDomains在 iOS 14+、macOS 11+ 启用 App-Bound Domains;更早系统打印版本要求并保留默认值。
javaScriptCanOpenWindowsAutomatically控制 JS 自动打开窗口。

从 1.4.10 起,可在创建 Widget 时选择手势策略:

WebViewWidget.fromPlatformCreationParams(
params: WebKitWebViewWidgetCreationParams(
controller: controller.platform,
uiKitGestureBlockingPolicy:
WebKitGestureBlockingPolicy.doNotBlockGesture,
),
);

默认使用 fallbackToPluginDefault。eager 和 waitUntilTouchesEnded 可用于较早的受支持 Flutter;doNotBlockGesture 需要 Flutter 3.47+,可用于规避部分触摸无响应 问题,但可能让 WebView 识别本应交给 Flutter 的手势。仅在遇到问题时选择, 并验证滚动和覆盖在 WebView 上的 Flutter 控件。

也接受新版 Flutter 的 UiKitViewGestureBlockingPolicy 枚举。旧 Flutter 请求 doNotBlockGesture,或在 macOS 请求非默认策略时,会打印说明并保留默认行为。

API作用
setAllowsBackForwardNavigationGestures启用滑动前进/后退。
setAllowsLinkPreview控制 link preview。
setOnCanGoBackChange监听 canGoBack 变化。
setInspectable在 iOS 16.4+、macOS 13.3+ 启用 WebKit inspect;更早系统打印版本要求并安全忽略。
loadFileWithParams(WebKitLoadFileParams)加载本地文件并设置可读范围。
await (controller.platform as WebKitWebViewController).loadFileWithParams(
WebKitLoadFileParams(
absoluteFilePath: '/Users/me/site/index.html',
readAccessPath: '/Users/me/site',
),
);

readAccessPath 必须覆盖 HTML 引用的本地资源。

WKWebView 会由 WebKit 自动处理 WebAuthn 请求,因此没有 Android 式的 启用开关,webview_all 也不增加这种伪统一接口。使用 Passkey 时,需要在 宿主应用的 Associated Domains 中配置 relying-party 域名,并按 Apple Passkey 文档 完成网站端关联。

Passkey 使用的 Associated Domains 与 limitsNavigationsToAppBoundDomains 不是同一项配置;启用 App-Bound Domains 不会自动开通 Passkey。实际能力还取决于系统版本和已安装的 凭据提供方,网页应使用标准 PublicKeyCredential 能力检测,并在不可用时 提供其他登录方式。

macOS 与 iOS 共用 Dart 包。macOS 端只使用公开原生 WebKit API,并在运行时判断系统版本;不会通过注入 JavaScript 模拟缺失的视图 API。

区域限制
滚动位置与回调macOS WKWebView 没有公开内部 scroll view;调用会打印说明并安全忽略,读取返回 Offset.zero。
滚动条与 overscrollmacOS 没有对应公开 API;调用会打印说明并安全忽略。
背景色macOS 12+ 使用原生 underPageBackgroundColor;更早系统打印版本要求并安全忽略。
缩放使用原生 allowsMagnification,不使用 JavaScript 兜底。
inspect需要 macOS 13.3+;更早系统打印版本要求并安全忽略。
link preview取决于系统支持。

这些兼容逻辑由 webview_all_wkwebview 子插件负责,主 webview_all Controller 不再包含 macOS 特判。

子插件会在 iOS application termination、受支持的 scene disconnect 或 Flutter engine detach 时进行幂等清理:停止向 Dart 发消息,并移除 Pigeon handler 和 instance;生命周期回调重复到达也不会出错。macOS 继续使用 Flutter 的 engine detach 回调。

当 Flutter engine 提供公开 scene 协议时,插件会自动注册 scene 生命周期。 iOS 原生 WKWebView 访问入口也支持传入 FlutterPluginRegistrar:可用时使用 Flutter 官方 registrar 查询,较早的受支持 Flutter 版本使用按 engine 隔离的兼容 查询,无需修改宿主应用。