Skip to content

Commit d8b4304

Browse files
authored
[webview_flutter] Add gesture blocking policy to WebKitWebViewWidgetCreationParams (flutter#12496)
Adds `WebKitWebViewWidgetCreationParams.uiKitGestureBlockingPolicy`, forwarded to `UiKitView.gestureBlockingPolicy`, so apps can opt in to an iOS gesture-blocking workaround when a web view becomes unresponsive to touches. The default remains `UiKitViewGestureBlockingPolicy.fallbackToPluginDefault`, preserving existing behavior. The parameter has no effect on macOS. The `uiKit` prefix makes the platform scope explicit and leaves room for a separate macOS policy. Native plugin registration is unchanged. ### Why the minimum Flutter version is bumped `UiKitView.gestureBlockingPolicy` landed in flutter#185126 and first shipped in stable **3.47.0** (it is not present in 3.44.x), so `flutter: ">=3.47.0"` is required to reference it at all. `validate` enforces a matching Dart lower bound, hence `sdk: ^3.13.0`, and that made this a minor version bump (`3.27.0`) rather than a patch. Raising the package's language version to Dart 3.13 changes `dart format` output for files that were already checked in. That reformat is isolated in the original formatting commit. Current `main` already includes the Flutter 3.47.0 SDK mapping, so this PR no longer changes `script/tool`. ### Behavior and validation `doNotBlockGesture` uses hit-test results to decide when to block the web view's gesture recognizers, without relying on Flutter's gesture arena. It remains an opt-in workaround that may allow gestures that should have been blocked. A widget test verifies that opting in still builds an `AppKitView` on macOS. Local validation on Flutter 3.47.2 / Dart 3.13.2: all 158 package tests pass, including 7 widget tests; static analysis, repository formatting, README excerpt synchronization, package validation and license checks pass. ### Before / after Both recorded on the same build against the same third-party cashier page, iOS 26.4 simulator (iPhone 17 Pro). `uiKitGestureBlockingPolicy` is the only difference between the two runs. **Before** — `fallbackToPluginDefault`, i.e. the `eager` policy the plugin registers the platform view with. The first touch is delivered; after that the web view is dead: taps do nothing and drags never move `window.scrollY`. https://github.com/user-attachments/assets/481d69d4-ba43-49fe-99dc-8534b79f67e3 **After** — `uiKitGestureBlockingPolicy: UiKitViewGestureBlockingPolicy.doNotBlockGesture`. Scrolling and tapping keep working for the rest of the session. https://github.com/user-attachments/assets/01e7516c-4b53-4b11-98ee-8bd1b7119c4a ### Minimal repro Still owed. I built a standalone project that mirrors the page shape which triggers it for us — a form taller than the viewport embedding four cross-origin iframes — and it does **not** reproduce, so the trigger is narrower than page geometry alone. The page that does trigger it reliably is a closed-source payment cashier I cannot share. I will keep reducing it. One data point in the meantime: `flutter_inappwebview` also registers its iOS platform view via the two-argument `registrar.register(_:withId:)` (so, `eager`), and shows the same symptom on iOS 26 on the same page — which suggests the underlying issue is not specific to `webview_flutter`. Related: flutter#175099, flutter#179907 Fixes flutter#191267 ## Pre-Review Checklist
1 parent 8dd3f95 commit d8b4304

21 files changed

Lines changed: 2168 additions & 2879 deletions

‎packages/webview_flutter/webview_flutter_wkwebview/CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
## 3.27.0
2+
3+
* Adds `WebKitWebViewWidgetCreationParams.uiKitGestureBlockingPolicy` for choosing the gesture
4+
blocking policy of the iOS platform view. Setting it to `doNotBlockGesture` works around web
5+
views becoming unresponsive to touches. See
6+
https://github.com/flutter/flutter/issues/175099.
7+
18
## 3.26.2
29

310
* Fixes a crash when a `WKNavigationDelegate` authentication challenge reply cannot be

‎packages/webview_flutter/webview_flutter_wkwebview/README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,27 @@ so you do not need to add it to your `pubspec.yaml`.
1111
However, if you `import` this package to use any of its APIs directly, you
1212
should add it to your `pubspec.yaml` as usual.
1313

14+
### Gesture blocking policy on iOS
15+
16+
If a web view stops responding to touches after the first interaction on iOS, using hit-test results
17+
instead of Flutter's gesture arena to decide when to block the web view's gesture recognizers can
18+
work around it:
19+
20+
<?code-excerpt "example/lib/readme_excerpts.dart (gesture_blocking_policy_example)"?>
21+
```dart
22+
final params = WebKitWebViewWidgetCreationParams(
23+
controller: controller,
24+
uiKitGestureBlockingPolicy: .doNotBlockGesture,
25+
);
26+
```
27+
28+
Pass those parameters to `WebViewWidget.fromPlatformCreationParams`, using the `platform` of your
29+
`WebViewController` as the `controller`.
30+
31+
This is a workaround for bugs in the underlying `WKWebView`, and it may cause the web view to
32+
recognize a gesture that should have been blocked, so only opt in when a web view is affected. The
33+
policy has no effect on macOS.
34+
1435
### External Native API
1536

1637
The plugin also provides a native API accessible by the native code of iOS applications or packages.

‎packages/webview_flutter/webview_flutter_wkwebview/example/integration_test/webview_flutter_test.dart‎

Lines changed: 37 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -155,9 +155,8 @@ Future<void> main() async {
155155
await tester.pumpWidget(
156156
Builder(
157157
builder: (BuildContext context) {
158-
return PlatformWebViewWidget(
159-
PlatformWebViewWidgetCreationParams(controller: controller),
160-
).build(context);
158+
return PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: controller))
159+
.build(context);
161160
},
162161
),
163162
);
@@ -181,9 +180,8 @@ Future<void> main() async {
181180
await tester.pumpWidget(
182181
Builder(
183182
builder: (BuildContext context) {
184-
return PlatformWebViewWidget(
185-
PlatformWebViewWidgetCreationParams(controller: controller),
186-
).build(context);
183+
return PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: controller))
184+
.build(context);
187185
},
188186
),
189187
);
@@ -208,18 +206,17 @@ Future<void> main() async {
208206
await tester.pumpWidget(
209207
Builder(
210208
builder: (BuildContext context) {
211-
return PlatformWebViewWidget(
212-
PlatformWebViewWidgetCreationParams(controller: controller),
213-
).build(context);
209+
return PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: controller))
210+
.build(context);
214211
},
215212
),
216213
);
217214

218215
await pageLoads.stream.firstWhere((String url) => url == headersUrl);
219216

220-
final content =
221-
await controller.runJavaScriptReturningResult('document.documentElement.innerText')
222-
as String;
217+
final content = await controller.runJavaScriptReturningResult(
218+
'document.documentElement.innerText',
219+
) as String;
223220
expect(content.contains('flutter_test_header'), isTrue);
224221
});
225222

@@ -236,9 +233,8 @@ Future<void> main() async {
236233
await tester.pumpWidget(
237234
Builder(
238235
builder: (BuildContext context) {
239-
return PlatformWebViewWidget(
240-
PlatformWebViewWidgetCreationParams(controller: controller),
241-
).build(context);
236+
return PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: controller))
237+
.build(context);
242238
},
243239
),
244240
);
@@ -270,9 +266,8 @@ Future<void> main() async {
270266
await tester.pumpWidget(
271267
Builder(
272268
builder: (BuildContext context) {
273-
return PlatformWebViewWidget(
274-
PlatformWebViewWidgetCreationParams(controller: controller),
275-
).build(context);
269+
return PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: controller))
270+
.build(context);
276271
},
277272
),
278273
);
@@ -306,9 +301,8 @@ Future<void> main() async {
306301
await tester.pumpWidget(
307302
Builder(
308303
builder: (BuildContext context) {
309-
return PlatformWebViewWidget(
310-
PlatformWebViewWidgetCreationParams(controller: controller),
311-
).build(context);
304+
return PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: controller))
305+
.build(context);
312306
},
313307
),
314308
);
@@ -353,9 +347,8 @@ Future<void> main() async {
353347
await tester.pumpWidget(
354348
Builder(
355349
builder: (BuildContext context) {
356-
return PlatformWebViewWidget(
357-
PlatformWebViewWidgetCreationParams(controller: controller),
358-
).build(context);
350+
return PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: controller))
351+
.build(context);
359352
},
360353
),
361354
);
@@ -372,9 +365,8 @@ Future<void> main() async {
372365
await tester.pumpWidget(
373366
Builder(
374367
builder: (BuildContext context) {
375-
return PlatformWebViewWidget(
376-
PlatformWebViewWidgetCreationParams(controller: controller),
377-
).build(context);
368+
return PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: controller))
369+
.build(context);
378370
},
379371
),
380372
);
@@ -682,9 +674,8 @@ Future<void> main() async {
682674
await tester.pumpWidget(
683675
Builder(
684676
builder: (BuildContext context) {
685-
return PlatformWebViewWidget(
686-
PlatformWebViewWidgetCreationParams(controller: controller),
687-
).build(context);
677+
return PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: controller))
678+
.build(context);
688679
},
689680
),
690681
);
@@ -1197,9 +1188,8 @@ Future<void> main() async {
11971188
await tester.pumpWidget(
11981189
Builder(
11991190
builder: (BuildContext context) {
1200-
return PlatformWebViewWidget(
1201-
WebKitWebViewWidgetCreationParams(controller: controller),
1202-
).build(context);
1191+
return PlatformWebViewWidget(WebKitWebViewWidgetCreationParams(controller: controller))
1192+
.build(context);
12031193
},
12041194
),
12051195
);
@@ -1230,9 +1220,8 @@ Future<void> main() async {
12301220
await tester.pumpWidget(
12311221
Builder(
12321222
builder: (BuildContext context) {
1233-
return PlatformWebViewWidget(
1234-
WebKitWebViewWidgetCreationParams(controller: controller),
1235-
).build(context);
1223+
return PlatformWebViewWidget(WebKitWebViewWidgetCreationParams(controller: controller))
1224+
.build(context);
12361225
},
12371226
),
12381227
);
@@ -1250,9 +1239,8 @@ Future<void> main() async {
12501239
await tester.pumpWidget(
12511240
Builder(
12521241
builder: (BuildContext context) {
1253-
return PlatformWebViewWidget(
1254-
PlatformWebViewWidgetCreationParams(controller: controller),
1255-
).build(context);
1242+
return PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: controller))
1243+
.build(context);
12561244
},
12571245
),
12581246
);
@@ -1275,9 +1263,8 @@ Future<void> main() async {
12751263
await tester.pumpWidget(
12761264
Builder(
12771265
builder: (BuildContext context) {
1278-
return PlatformWebViewWidget(
1279-
PlatformWebViewWidgetCreationParams(controller: controller),
1280-
).build(context);
1266+
return PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: controller))
1267+
.build(context);
12811268
},
12821269
),
12831270
);
@@ -1300,9 +1287,8 @@ Future<void> main() async {
13001287
await tester.pumpWidget(
13011288
Builder(
13021289
builder: (BuildContext context) {
1303-
return PlatformWebViewWidget(
1304-
PlatformWebViewWidgetCreationParams(controller: controller),
1305-
).build(context);
1290+
return PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: controller))
1291+
.build(context);
13061292
},
13071293
),
13081294
);
@@ -1338,9 +1324,8 @@ Future<void> main() async {
13381324
await tester.pumpWidget(
13391325
Builder(
13401326
builder: (BuildContext context) {
1341-
return PlatformWebViewWidget(
1342-
PlatformWebViewWidgetCreationParams(controller: controller),
1343-
).build(context);
1327+
return PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: controller))
1328+
.build(context);
13441329
},
13451330
),
13461331
);
@@ -1366,9 +1351,8 @@ Future<void> main() async {
13661351
await tester.pumpWidget(
13671352
Builder(
13681353
builder: (BuildContext context) {
1369-
return PlatformWebViewWidget(
1370-
PlatformWebViewWidgetCreationParams(controller: controller),
1371-
).build(context);
1354+
return PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: controller))
1355+
.build(context);
13721356
},
13731357
),
13741358
);
@@ -1392,9 +1376,8 @@ Future<void> main() async {
13921376
await tester.pumpWidget(
13931377
Builder(
13941378
builder: (BuildContext context) {
1395-
return PlatformWebViewWidget(
1396-
PlatformWebViewWidgetCreationParams(controller: controller),
1397-
).build(context);
1379+
return PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: controller))
1380+
.build(context);
13981381
},
13991382
),
14001383
);

‎packages/webview_flutter/webview_flutter_wkwebview/example/lib/main.dart‎

Lines changed: 10 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -208,9 +208,8 @@ Page resource error:
208208
JavaScriptChannelParams(
209209
name: 'Toaster',
210210
onMessageReceived: (JavaScriptMessage message) {
211-
ScaffoldMessenger.of(
212-
context,
213-
).showSnackBar(SnackBar(content: Text(message.message)));
211+
ScaffoldMessenger.of(context)
212+
.showSnackBar(SnackBar(content: Text(message.message)));
214213
},
215214
),
216215
)
@@ -245,9 +244,8 @@ Page resource error:
245244
SampleMenu(webViewController: _controller, cookieManager: widget.cookieManager),
246245
],
247246
),
248-
body: PlatformWebViewWidget(
249-
PlatformWebViewWidgetCreationParams(controller: _controller),
250-
).build(context),
247+
body: PlatformWebViewWidget(PlatformWebViewWidgetCreationParams(controller: _controller))
248+
.build(context),
251249
floatingActionButton: favoriteButton(),
252250
);
253251
}
@@ -495,9 +493,8 @@ class SampleMenu extends StatelessWidget {
495493
'caches.open("test_caches_entry"); localStorage["test_localStorage"] = "dummy_entry";',
496494
);
497495
if (context.mounted) {
498-
ScaffoldMessenger.of(
499-
context,
500-
).showSnackBar(const SnackBar(content: Text('Added a test entry to cache.')));
496+
ScaffoldMessenger.of(context)
497+
.showSnackBar(const SnackBar(content: Text('Added a test entry to cache.')));
501498
}
502499
}
503500

@@ -739,9 +736,8 @@ class NavigationControls extends StatelessWidget {
739736
await webViewController.goBack();
740737
} else {
741738
if (context.mounted) {
742-
ScaffoldMessenger.of(
743-
context,
744-
).showSnackBar(const SnackBar(content: Text('No back history item')));
739+
ScaffoldMessenger.of(context)
740+
.showSnackBar(const SnackBar(content: Text('No back history item')));
745741
}
746742
}
747743
},
@@ -753,9 +749,8 @@ class NavigationControls extends StatelessWidget {
753749
await webViewController.goForward();
754750
} else {
755751
if (context.mounted) {
756-
ScaffoldMessenger.of(
757-
context,
758-
).showSnackBar(const SnackBar(content: Text('No forward history item')));
752+
ScaffoldMessenger.of(context)
753+
.showSnackBar(const SnackBar(content: Text('No forward history item')));
759754
}
760755
}
761756
},
Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// Copyright 2013 The Flutter Authors
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'package:webview_flutter_platform_interface/webview_flutter_platform_interface.dart';
6+
import 'package:webview_flutter_wkwebview/webview_flutter_wkwebview.dart';
7+
8+
/// Example function for README demonstration of the gesture blocking policy.
9+
PlatformWebViewWidgetCreationParams createParamsWithoutGestureBlocking(
10+
PlatformWebViewController controller,
11+
) {
12+
// #docregion gesture_blocking_policy_example
13+
final params = WebKitWebViewWidgetCreationParams(
14+
controller: controller,
15+
uiKitGestureBlockingPolicy: .doNotBlockGesture,
16+
);
17+
// #enddocregion gesture_blocking_policy_example
18+
return params;
19+
}

‎packages/webview_flutter/webview_flutter_wkwebview/example/pubspec.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@ description: Demonstrates how to use the webview_flutter_wkwebview plugin.
33
publish_to: none
44

55
environment:
6-
sdk: ^3.11.0
7-
flutter: ">=3.41.0"
6+
sdk: ^3.13.0
7+
flutter: ">=3.47.0"
88

99
dependencies:
1010
flutter:

‎packages/webview_flutter/webview_flutter_wkwebview/lib/src/webkit_ssl_auth_error.dart‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
import 'package:flutter/services.dart';
66
import 'package:meta/meta.dart';
77
import 'package:webview_flutter_platform_interface/webview_flutter_platform_interface.dart';
8+
89
import 'common/web_kit.g.dart';
910

1011
/// An implementation of [PlatformSslAuthError] with the WebKit api.

0 commit comments

Comments
 (0)