[webview_flutter] Add gesture blocking policy to WebKitWebViewWidgetCreationParams - #12496

In Swift, Objective-C enums are imported with shortened, idiomatic names. You can use .doNotBlockGesture instead of the verbose FlutterPlatformViewGestureRecognizersBlockingPolicyDoNotBlockGesture to make the code cleaner and more idiomatic.

      registrar.register(
        viewFactory, withId: "plugins.flutter.io/webview",
        gestureRecognizersBlockingPolicy: .doNotBlockGesture)

.doNotBlockGesture does not compile here. The policy is declared in FlutterPlugin.h as a plain C enum:

typedef enum {
  FlutterPlatformViewGestureRecognizersBlockingPolicyEager,
  FlutterPlatformViewGestureRecognizersBlockingPolicyWaitUntilTouchesEnded,
  FlutterPlatformViewGestureRecognizersBlockingPolicyDoNotBlockGesture,
} FlutterPlatformViewGestureRecognizersBlockingPolicy;

Because it is not declared with NS_ENUM, the Swift importer does not shorten the case names. Building an app against Flutter 3.47.0 with the shortened form fails with:

Swift Compiler Error: Type 'FlutterPlatformViewGestureRecognizersBlockingPolicy' has no member 'doNotBlockGesture'

So the fully qualified constant is intentional. Happy to switch if the enum is ever annotated for Swift.

We should pass in the policy from the dart side instead: https://github.com/flutter/flutter/blob/f6061d0003a7a9e0cb30a45379c4c4bec0412c40/packages/flutter/lib/src/services/platform_views.dart#L1630

I'm glad that the new doNotBlockGesture policy works for you. However, this policy is designed as the last resort to deal with bugs of the platform view itself (e.g. WKWebView).

So it would be great if you can provide a reproducible project so we can look further.

Thanks for the review, and understood on doNotBlockGesture being a last resort rather than a default.

I'm still actively on this and will follow up on both points:

1. Reproducible project — I'll put together a minimal app that shows the web view going unresponsive after the first interaction on iOS 26 and link it here, so the underlying platform-view/WebKit behaviour can be investigated properly instead of just being worked around at the registration site.
2. Passing the policy from the Dart side — that makes sense; hardcoding it in WebViewFlutterPlugin takes the decision away from the app. I'll look into plumbing it through the plugin's Dart layer so it's opt-in per web view, and rework this PR in that shape if you'd prefer that over the unconditional change.

I'd rather land the right fix than the convenient one, so I'll hold this PR until the repro is up. Please leave it open in the meantime — I'll ping you here once both are ready.

Done — the policy now comes from the Dart side and the plugin registration is back to what it was on main.

WebKitWebViewWidgetCreationParams.gestureBlockingPolicy is forwarded to UiKitView.gestureBlockingPolicy, defaulting to fallbackToPluginDefault. So nothing changes for existing apps, and doNotBlockGesture stays an explicit opt-in rather than a new default — which matches your point about it being a last resort.

One consequence worth flagging: UiKitView.gestureBlockingPolicy first shipped in stable 3.47.0, so the package's minimum Flutter had to move to >=3.47.0 (and Dart to ^3.13.0 for consistency, making this 3.27.0). That also needed a getDartSdkForFlutterSdk entry for 3.47.0 in script/tool, and it changes dart format output for some already-checked-in files — that reformat is isolated in the second commit so the API change stays readable.

Still working on the repro project; I'll link it here rather than hold the code change for it. One data point while I put it together: flutter_inappwebview also registers its iOS platform view through the two-argument registrar.register(_:withId:), i.e. eager, and shows the same symptom on iOS 26 in the same app. Two independent plugins with the same default and the same failure suggests this is not webview_flutter-specific, which may help narrow down where the arena state is getting stranded.

Two independent plugins with the same default and the same failure suggests this is not webview_flutter-specific, which may help narrow down where the arena state is getting stranded.

This is likely a bug in WKWebView, which is used by both this package & flutter_inappwebview, so it happens on both.

That's fair — I was reading the shared eager default as the common factor, but WKWebView itself is just as good an explanation for the same data, and I don't have anything that distinguishes the two yet. So I've taken the causal wording out of the README and the doc comment; I'll leave the cause open until there's a repro that actually shows one.

Still putting the minimal project together and I'll link it here.

(Also force-pushed the branch: the commits carried a co-author trailer that was failing the CLA check. Only the commit messages and the two doc changes above differ from what you reviewed.)

Using the idiomatic Swift enum case .doNotBlockGesture simplifies the assertion and improves readability.

      #expect(registrar.registeredGestureRecognizersBlockingPolicy == .doNotBlockGesture)

Same reason as the other comment: the enum is declared as a plain C typedef enum rather than NS_ENUM, so the Swift importer keeps the full constant names and .doNotBlockGesture fails to compile.

We should pass in the policy from the dart side instead: https://github.com/flutter/flutter/blob/f6061d0003a7a9e0cb30a45379c4c4bec0412c40/packages/flutter/lib/src/services/platform_views.dart#L1630

I'm glad that the new doNotBlockGesture policy works for you. However, this policy is designed as the last resort to deal with bugs of the platform view itself (e.g. WKWebView).

So it would be great if you can provide a reproducible project so we can look further.

I would avoid this description, since we don't know what's happening yet.

Thanks — done. The README no longer claims the arena state is stranded; it just describes the symptom and what the policy does instead:

By default the plugin lets the engine block the web view's gesture recognizers through Flutter's gesture arena. If a web view stops responding to touches after the first interaction, deriving the blocking decision from hit testing instead can work around it:

The flutter/flutter#175099 link reference is removed along with it.

I'd delete these 2 since we are not 100% sure this is indeed the cause yet.

Thanks — removed. Both bullets and the See also: block are gone, and so is the paragraph above them that made the same claim about stranded arena state. What's left only describes the behaviour and the trade-off:

/// Setting this to [UiKitViewGestureBlockingPolicy.doNotBlockGesture]
/// derives the blocking decision from hit testing instead of Flutter's
/// gesture arena, which can work around a web view that stops responding to
/// touches, at the cost of the web view potentially recognizing a gesture
/// that should have been blocked.

this build call isn't introduced in the PR but build is supposed to be a @protected method. It shouldn't be called directly.

Agreed. Those calls are pre-existing — only the line wrapping changed here, from the 3.13 reformat. Left alone to keep this PR scoped; happy to file a follow-up issue if useful.

nit: it looks like you can use dot shorthands here instead of specifying the full qualifier?

Done.

Would it be better to rename this uiKitGestureBlockingPolicy to emphasize this is iOS only?

UiKitView.gestureBlockingPolicy doesn't have that prefix but it's already called UiKitView.

Kept as gestureBlockingPolicy to match UiKitView.gestureBlockingPolicy, and made the iOS-only scope explicit in the doc comment and README instead. Say the word if you still want uiKitGestureBlockingPolicy — nothing depends on the name yet.

I am not sure about the convention here. @LongCatIsLooong can you advice?

Sorry for the delay, after speaking @hellohuanlin offline I think I'm still leaning towards adding the prefix since UiKitView is iOS only but wkwebview is also available on macOS so the context is a bit different.
Also with a prefix it's less likely to have a naming collision if we need a separate parameter to control the gesture blocking behavior on macOS.

Renamed the public parameter to uiKitGestureBlockingPolicy, including the constructor, equality/hashCode, tests, README and executable example. It is still forwarded to UiKitView.gestureBlockingPolicy and defaults to fallbackToPluginDefault. Added a widget test confirming that the iOS-specific option still builds AppKitView on macOS.

I read the docs and the first sentence is a bit confusing:

/// Causes iOS engine to block all the UIGestureRecognizers on the platform view if it deems
/// the hittest shouldn't be handled by the Flutter framework.

@hellohuanlin did you mean "shift the gesture disambiguation responsibility entirely to UIKit and the UIKit view hierarchy" instead of "blocking all `UIGestureRecognizers" on the platform view?

I think the original comment i wrote is clearer: https://github.com/flutter/flutter/blob/a981f46cbcf5059e7cafea2f469025a5c6071e5f/engine/src/flutter/shell/platform/darwin/ios/framework/Headers/FlutterPlugin.h#L273-L278

Updated the doc comment and README to match the engine header: Flutter blocks the web view's gesture recognizers based on hit-test results, without relying on Flutter's gesture arena. Removed the unconditional “never blocks” wording and retained the opt-in workaround caveat.

It's not clear to me what "derives the blocking decision from hit testing ..." means, I suppose this is "touch events that reach this platform view will be consumed by the UIKit view hierarchy and will not be dispatched to the flutter framework?". In any case, can this sentence be simplified to something to the effect of "flutter never blocks touch events that land on this view"?

Used your wording: "Flutter never blocks touches that land on the web view: they are handled by the web view and are not disambiguated through Flutter's gesture arena." The hit-testing phrasing is gone.

It's not clear which "gesture recognizers" are the subject of the blocking, the flutter gesture recognizers, or the UIKit ones?

Reworded — it is the UIGestureRecognizers the WKWebView installs on itself, blocked by Flutter. Made that explicit.

Uhh is there a formatter change or a pigeon version bump? Is this a formatting-only change?

Formatting only, no pigeon bump. The Dart 3.13 minimum raises the language version, which changes dart format output. Verified: the file from main run through dart format --page-width=100 on Dart 3.13.0 reproduces this version exactly. Isolated in the second commit.

maybe: Gesture blocking policy on iOS

Or even "If a web view stops responding to touches after the first interaction on iOS" since you're mainly describing a workaround to a webview bug.

(this only affects iOS I assume)?

Yes, iOS only. Heading is now "Gesture blocking policy on iOS", the sentence says "on iOS", and I added that the policy has no effect on macOS.

Sorry for the delay, after speaking @hellohuanlin offline I think I'm still leaning towards adding the prefix since UiKitView is iOS only but wkwebview is also available on macOS so the context is a bit different.
Also with a prefix it's less likely to have a naming collision if we need a separate parameter to control the gesture blocking behavior on macOS.