如何解决WKWebView中AVPlayerViewController全屏手势与UIPanGestureRecognizer冲突问题？

WKWebView承载的视频播放，默认在iPhone上点击<video>元素会调用系统AVPlayerViewController进入全屏。开发中我们经常在WKWebView的父视图或主window上添加UIPanGestureRecognizer，用来实现侧滑返回、下拉关闭或全屏边缘拖拽。只要这个Pan手势没有针对视频区域做过滤，全屏后手指在播放器上的滑动就会同时被系统手势和自定义Pan手势捕获。表现为视频全屏界面跟着父视图移动、控制条连续闪烁，或者全屏转屏动画中途被打断。

一、冲突链路与手势识别机制

在WKWebView上直接添加Pan手势，默认会附加到WKWebView的视图层级。当视频全屏时，AVPlayerViewController会创建一个独立的UIWindow或者在新的UIScene中呈现，系统视频控制层的手势也在这个新window中。如果自定义Pan手势被添加在原始window或者WKWebView上，按照iOS触摸传递规则，触摸只会命中当前keyWindow的视图，理论上不应该跨window。但很多应用将Pan手势添加到了keyWindow，或者通过UIApplication的windows数组找到最顶层window添加手势，这就导致全屏后手势依然能监控到触摸。此外，WKWebView内部的UIScrollView也有自己的pan手势，当视频元素被点击全屏后，系统私有手势与scrollview手势竞争，此时如果没有正确配置delegate，两个手势的识别状态会互相影响。

理解手势识别器的三个关键方法很重要：shouldBegin返回false可让手势不识别本次触摸，shouldReceive返回false可让手势忽略特定视图的触摸，shouldRecognizeSimultaneously返回true可让两个手势同时识别。AVPlayerViewController全屏后的控制层通过私有类接收触摸，自定义Pan通常会被当作备选手势。系统手势在识别成功后，如果自定义Pan同时被允许识别，就会看到播放器上层UI被拖拽。多数问题的本质不是系统手势不释放，而是自定义Pan的代理范围太宽。

二、错误配置与常见代理误区

一种常见错误是只设置panGesture.delegate = self，但未实现任何代理方法。这样UIPanGestureRecognizer会按照默认优先级参与竞争，往往与AVPlayerViewController的系统手势互相取消。另一种错误是直接把panGesture.cancelsTouchesInView = false，认为不取消触摸就不会影响视频。但全屏后触摸对象不再是WKWebView，这个属性只影响原始视图，无法约束新window中的视频控制层。还有一种错误是调用requireGestureRecognizerToFail，试图让自定义Pan依赖于系统手势失败。这个方案在部分场景下有效，但会造成滑动返回延迟，且当系统手势不暴露时无法指定依赖对象。

正确做法先缩小手势作用域，让pan只在WKWebView的scrollView上生效，然后在delegate中判断当前触摸是否落在视频区域。代码示例如下：

import UIKit
import WebKit

class VideoWebViewController: UIViewController {
    let webView = WKWebView()
    var panGesture: UIPanGestureRecognizer!

    override func viewDidLoad() {
        super.viewDidLoad()
        view.addSubview(webView)
        // 将pan手势添加到webView的scrollView，避免绑定到整个window
        panGesture = UIPanGestureRecognizer(target: self, action: #selector(handlePan(_:)))
        panGesture.delegate = self
        webView.scrollView.addGestureRecognizer(panGesture)
    }

    @objc func handlePan(_ gesture: UIPanGestureRecognizer) {
        let translation = gesture.translation(in: webView)
        // 处理自定义拖拽逻辑
        print("translation: \(translation)")
    }
}

extension VideoWebViewController: UIGestureRecognizerDelegate {
    func gestureRecognizer(_ gestureRecognizer: UIGestureRecognizer,
                           shouldRecognizeSimultaneouslyWith otherGestureRecognizer: UIGestureRecognizer) -> Bool {
        // 仅当另一个手势不是视频相关私有手势时，才允许同时识别
        // 这里为了演示直接返回false，实际可做类型过滤
        return false
    }

    func gestureRecognizer(_ gestureRecognizer: UIGestureRecognizer,
                           shouldReceive touch: UITouch) -> Bool {
        // 若触摸发生在视频区域，返回false，避免抢手势
        let point = touch.location(in: webView)
        if let videoView = findVideoView(in: webView), videoView.frame.contains(point) {
            return false
        }
        return true
    }

    func findVideoView(in view: UIView) -> UIView? {
        for subview in view.subviews {
            if String(describing: type(of: subview)).lowercased().contains("video") {
                return subview
            }
            if let found = findVideoView(in: subview) {
                return found
            }
        }
        return nil
    }
}

但仅靠上面的递归查找视频区域脆弱，因为全屏后视频视图可能不在WKWebView的子层级，而是在新的UIWindow中。因此需要配合全屏状态监听动态禁用手势。

三、动态监听全屏状态并隔离手势

AVPlayerViewController在进入和退出全屏时，会发送一些系统通知。iOS没有公开的专门通知，但可以通过观察UIWindow的didBecomeVisibleNotification、UIDevice的orientation变化，或者KVO监听WKWebView内部AVPlayerViewController的presentation状态。更稳定的方式是在H5端配合，当视频进入全屏时通过JavaScript调用原生方法通知禁用手势，退出时再恢复。原生侧可以监听UIWindow通知，判断新出现的window是否包含AVPlayerViewController的view。

下面代码监听窗口变化，如果检测到当前最上层window描述中包含AVPlayerViewController，则将自定义pan手势设为禁用。

import UIKit

extension VideoWebViewController {
    func setupWindowObserver() {
        NotificationCenter.default.addObserver(self,
                                               selector: #selector(windowDidBecomeVisible(_:)),
                                               name: UIWindow.didBecomeVisibleNotification,
                                               object: nil)
    }

    @objc func windowDidBecomeVisible(_ notification: Notification) {
        guard let window = notification.object as? UIWindow else { return }
        let windowDesc = String(describing: type(of: window))
        if windowDesc.contains("AVPlayer") || windowDesc.contains("FullScreen") {
            panGesture.isEnabled = false
        } else {
            panGesture.isEnabled = true
        }
    }

    deinit {
        NotificationCenter.default.removeObserver(self)
    }
}

禁用pan手势会立刻释放触摸，系统全屏播放器的控制层可以完整接收滑动。恢复时机要设置在退出全屏的窗口隐藏通知中，否则返回页面后自定义侧滑会失效。UIWindow的didResignKeyNotification和didBecomeKeyNotification也可以作为辅助。

四、边界情况与最终稳定方案

在iPad分屏、多场景、画中画等场景下，AVPlayerViewController可能不会创建新window，而是以子视图方式嵌入。这时候动态禁用可能失效。更好的做法是重新设计手势挂载点，把自定义Pan加到WKWebView自己身上，而不要加到window；同时检查触摸点的view是否属于video子视图。对于需要全局边缘拖拽的App，可以在全屏期间只保留视频系统手势，退出全屏后再恢复。

另外，H5页面的视频元素可能会通过CSS禁用原生全屏，改用网页内自定义播放器，此时冲突会消失，但用户体验可能下降。如果必须原生全屏，建议同时设置webView.allowsBackForwardNavigationGestures = true，让系统处理返回手势，避免自定义Pan干扰。最终测试时，重点回归：视频全屏横竖屏切换、全屏内滑动控制条、退出全屏后的页面侧滑，确保三个动作互不冲突。

整个解决思路可以概括为：限制手势作用域、动态监听全屏窗口、必要时禁用手势。在手势代理中精确控制shouldReceive和shouldRecognizeSimultaneously，再配合窗口通知，可以稳定解决WKWebView视频播放器全屏手势与UIPanGestureRecognizer之间的交互冲突。

WKWebViewAVPlayerViewControllerUIPanGestureRecognizer修改时间：2026-10-03 22:20:01