在 iOS 开发里present 一个服务列表弹窗、签到弹窗、抽奖弹窗是很常见的需求。而“present 控制后点击背景消失点击弹出的位置接收点击事件”这句话几乎是每个客户端需求文档里都会出现的一句话。刚开始做的时候我觉得它简单到不值一提直到“点击内容卡片背景手势把它关掉了”和“背景怎么点都没反应”两个问题交替出现才意识到这行简洁需求的背后是一整套事件分发机制。这篇就完整记录我踩过的坑、最终采用的方案以及封装弹窗组件时值得注意的细节。1. 需求拆解点击背后的视图层级逻辑1.1 “背景”和“内容”在渲染层其实是两个实体先说结论屏幕上看起来是“一个弹窗”但在 iOS 的视图层级里至少有遮罩层和内容层两个独立视图。遮罩层一般是半透明黑色 UIView用于弱化底层页面、聚焦弹窗内容内容层是白色圆角卡片、按钮、列表等交互控件的容器。“点击背景消失”的意思是手指落在遮罩层可视区域时出发点是“关闭弹窗”这个动作。“点击弹出的位置接收点击事件”的意思是手指落在内容层区域时出发点是“按钮点击”“列表选择”“输入框聚焦”等业务动作。这两个区域在视觉上界限分明但在事件分发的角度系统只认 hitTest 的结果——触摸点命中的那个 view 是谁事件就首先传给谁。所以方案设计的关键不是“怎么判断用户点没点到背景”而是“如何让背景区域和内容区域的事件目标互不干扰”。1.2 系统默认的 present 并不满足需求直接调用present(_:animated:completion:)时系统默认的 modalPresentationStyle 在 iOS 13 之后是 pageSheet 或者 automatic呈现出来的是一个几乎全屏、带毛玻璃背景的页面。这种样式自带下滑关闭手势但和“点击背景消失”的交互形态完全不同。退一步说就算你强行给默认弹出的页面加一个透明遮罩让 presentedViewController.view 的背景变成半透明黑色也会遇到一个问题presentedViewController.view 默认占据整个 containerView 的 bounds也就是整个屏幕。它把下面的“背景”完全盖住了背景层根本接收不到触摸事件。这不是简单的代码写错而是视图层级天然决定的。所以要实现需求必须先改变呈现样式要么用 UIModalPresentationCustom让系统允许我们通过 UIPresentationController 精准控制层级和尺寸要么用 overFullScreen让 presentedViewController.view 本身承担遮罩角色内容作为它的子视图。1.3 两种主流方案的选型对比我实际用过两类方案各有适用场景先给结论方案核心思路优点缺点UIPresentationController 卡片弹窗内容视图独立占一块 frame遮罩视图在其下方层级天然隔离点击处理最干净需要额外写转场代理代码量稍多overFullScreen 手势代理弹窗控制器视图本身就是全屏遮罩内容作为子视图灵活适合底部弹层、不规则布局需要处理手势 shouldReceive否则容易误触如果你要写的是居中卡片式弹窗比如抽奖、公告、优惠券详情方案一是首选。如果你要写的是底部弹层、筛选面板、菜单选择器方案二更顺手。下面两个方案我分别展开代码可以直接抄。2. 方案一UIPresentationController 原生卡片弹窗2.1 自定义 Modal 样式准备使用 UIModalPresentationCustom 时系统会把控制权交给 UIViewControllerTransitioningDelegate 的presentationController(forPresented:presenting:source:)方法。我们在这里返回 UIPresentationController 的子类。这个子类掌管遮罩视图、内容 view 的尺寸和转场结束后的布局。先写 PresentationController 子类final class CardPresentationController: UIPresentationController { private let dimmingView UIView() private let contentSize: CGSize private var tapGesture: UITapGestureRecognizer! init(presentedViewController: UIViewController, presenting presentingViewController: UIViewController?, contentSize: CGSize) { self.contentSize contentSize super.init(presentedViewController: presentedViewController, presenting: presentingViewController) setupDimmingView() } private func setupDimmingView() { dimmingView.backgroundColor UIColor.black.withAlphaComponent(0.45) tapGesture UITapGestureRecognizer(target: self, action: #selector(handleTapOnDimming(_:))) dimmingView.addGestureRecognizer(tapGesture) } override var frameOfPresentedViewInContainerView: CGRect { guard let containerView containerView else { return .zero } return CGRect( x: (containerView.bounds.width - contentSize.width) / 2, y: (containerView.bounds.height - contentSize.height) / 2, width: contentSize.width, height: contentSize.height ) } override func presentationTransitionWillBegin() { super.presentationTransitionWillBegin() guard let containerView containerView else { return } dimmingView.frame containerView.bounds dimmingView.alpha 0 dimmingView.autoresizingMask [.flexibleWidth, .flexibleHeight] containerView.insertSubview(dimmingView, at: 0) presentedView?.layer.cornerRadius 16 presentedView?.layer.masksToBounds true presentedViewController.transitionCoordinator?.animate( alongsideTransition: { _ in self.dimmingView.alpha 1 }, completion: nil) } override func dismissalTransitionWillBegin() { super.dismissalTransitionWillBegin() presentedViewController.transitionCoordinator?.animate( alongsideTransition: { _ in self.dimmingView.alpha 0 }, completion: nil) } objc private func handleTapOnDimming(_ sender: UITapGestureRecognizer) { presentedViewController.dismiss(animated: true, completion: nil) } }注意frameOfPresentedViewInContainerView返回的 CGRect 决定了内容卡片的位置和大小。居中卡片的计算就是“容器宽减去内容宽除以 2”高度同理。这里最容易犯的错误是拿 presentingViewController.view.bounds 去算标准做法必须参考 containerView.bounds。2.2 用 frameOfPresentedViewInContainerView 限定内容尺寸为什么这步很关键因为如果不重写 frameOfPresentedViewInContainerViewpresentedView 默认会是 containerView 的整个 bounds也就是全屏。全屏的 presentedView 会把 dimmingView 完全遮住用户点哪里都只命中 presentedView背景永远不会触发关闭。所以核心思路就是让内容 view 只占用弹窗卡片那么大的一块区域其余屏幕区域全部暴露给 dimmingView。我看到不少团队用preferredContentSize 重写sizeForChildContentContainer来做本质上也是把 presentedView 的最终 size 算出来。但直接重写 frame 最直观、最可控对新手也比较友好。如果你需要在旋转屏幕后重新计算位置可以配合containerViewWillLayoutSubviews()方法更新 dimmingView.frame并把 presentedViewController.view.frame 重新赋值override func containerViewWillLayoutSubviews() { super.containerViewWillLayoutSubviews() dimmingView.frame containerView?.bounds ?? .zero presentedView?.frame frameOfPresentedViewInContainerView }这一步在 iPhone 横竖屏切换时非常有用否则卡片位置可能飘掉。2.3 点击遮罩 dismiss 的触发逻辑dimmingView 上添加的 UITapGestureRecognizertarget 直接指向handleTapOnDimming手势一旦识别就调用presentedViewController.dismiss(animated:completion:)。这里有一个底层机制值得理解UITapGestureRecognizer 添加到 dimmingView 上之后系统只会在“触摸命中 dimmingView 本身或其子视图”时去判断手势。dimmingView 在 containerView 的 index 0presentedView 在 index 1它们是兄弟视图关系。点击内容卡片时hitTest 命中的是 presentedView所以 dimmingView 上的手势根本不会参与识别。这就是兄弟层级带来的天然隔离。为什么不用touchesBegan去判断因为touchesBegan是 view 的触摸回调在 dimmingView 上重写它虽然也能实现背景点击但容易出现触摸被 subview 抢走、重复调用等问题。UITapGestureRecognizer 的识别逻辑更加独立还支持shouldReceive代理做二次过滤容错空间更大。2.4 点击内容区域为什么不会被误判关闭在方案一的层级结构里根本不需要额外写“判断点是否在内容区域”的逻辑。用户点内容卡片时触摸事件的目标视图是 presentedView 或者它的子视图事件根本不会传递到 dimmingView。于是按钮的点击、列表的滚动都能正常响应。这是我喜欢方案一的最大原因代码里不需要维护坐标判断不存在误判分支。你只需要保证内容区域确实是呈现出来的 presentedView.frame而不是把内容卡片做成一个全屏透明 controller 的 subview。需要留意的是 presentedViewController.view 的背景色。如果后台代码在 viewDidLoad 里把 view.backgroundColor 设成了白色或者半透明颜色卡片的大小跟视觉内容可能不匹配。实际开发中我会把 presentedViewController.view.backgroundColor 设置为 .clear然后在内容卡片内部单独设置背景色、圆角和阴影。2.5 转场代理必须强引用这里有个经典坑不亚于主逻辑本身。UIViewController 的transitioningDelegate属性是 weak 的如果你在 show 弹窗时写presenter.present(vc, animated: true) { vc.transitioningDelegate nil // 或者局部变量 }或者初始化时使用了局部代理对象这个 delegate 在 present 过程中就被释放了轻则自定义样式失效重则直接崩溃。正确做法是让 presentedViewController 持有代理对象的强引用final class CardPopupViewController: UIViewController { private lazy var cardTransitioningDelegate CardTransitioningDelegate( contentSize: CGSize(width: 300, height: 240) ) override init(nibName nibNameOrNil: String?, bundle nibBundleOrNil: Bundle?) { super.init(nibName: nibNameOrNil, bundle: nibBundleOrNil) modalPresentationStyle .custom transitioningDelegate cardTransitioningDelegate } }CardTransitioningDelegate 实现如下final class CardTransitioningDelegate: NSObject, UIViewControllerTransitioningDelegate { private let contentSize: CGSize private var cardPresentationController: CardPresentationController? init(contentSize: CGSize) { self.contentSize contentSize } func presentationController( forPresented presented: UIViewController, presenting: UIViewController?, source: UIViewController ) - UIPresentationController? { let controller CardPresentationController( presentedViewController: presented, presenting: presenting, contentSize: contentSize ) cardPresentationController controller return controller } }这种写法同样适用于其他需要自定义 presentation controller 的场景。强引用代理对象是我个人在实际项目中最常向同事强调的一条纪律。3. 方案二overFullScreen 全屏透明视图 手势代理3.1 构建弹窗视图结构不在方案一适用范围内的弹窗比如底部弹出的筛选面板或内容区域不规则的浮层更适合直接用 overFullScreen 手势代理。基本结构是这样的presentedViewController.view 设置为全屏、backgroundColor 半透明黑色作为整个遮罩内容卡片作为它的一个 subview。点击全屏视图上“内容卡片 frame 之外”的区域时关闭弹窗点击内容卡片内部时正常响应按钮。final class SheetPopupViewController: UIViewController, UIGestureRecognizerDelegate { private let contentView UIView() override func viewDidLoad() { super.viewDidLoad() modalPresentationStyle .overFullScreen view.backgroundColor UIColor.black.withAlphaComponent(0.5) contentView.backgroundColor UIColor.white contentView.layer.cornerRadius 12 contentView.translatesAutoresizingMaskIntoConstraints false view.addSubview(contentView) NSLayoutConstraint.activate([ contentView.leadingAnchor.constraint(equalTo: view.leadingAnchor), contentView.trailingAnchor.constraint(equalTo: view.trailingAnchor), contentView.bottomAnchor.constraint(equalTo: view.bottomAnchor), contentView.heightAnchor.constraint(equalToConstant: 360) ]) let tap UITapGestureRecognizer(target: self, action: #selector(backgroundTapped(_:))) tap.delegate self view.addGestureRecognizer(tap) } func gestureRecognizer(_ gestureRecognizer: UIGestureRecognizer, shouldReceive touch: UITouch) - Bool { let point touch.location(in: view) return !contentView.frame.contains(point) } objc private func backgroundTapped(_ sender: UITapGestureRecognizer) { dismiss(animated: true, completion: nil) } }这段代码里最关键的就是gestureRecognizer(_:shouldReceive:)。它的执行时机是手势识别器准备处理触摸事件之前返回 false 表示“这个触摸不参与当前手势的识别”。当用户点击 contentView 区域时系统会先把 touch.location 换算到 view 坐标系然后判断这个点是否落在 contentView.frame 内。落在内部就返回 false手势不识别事件继续向下传递给 contentView 里的按钮落在外部就返回 true手势正常识别触发关闭。注意modalPresentationStyle .overFullScreen是必须的。如果忘了设置默认可能是 pageSheetpresentedViewController.view 并不会全屏铺满整个遮罩结构都错了。3.2 坐标换算的大坑frame 的参照系方案二最容易被坑的地方就是contentView.frame的参照系。contentView 是 view 的子视图因此 contentView.frame 已经是相对 view 的坐标。而touch.location(in: view)返回的是相对 view 的点二者坐标系一致可以直接用contentView.frame.contains(point)判断。但如果 contentView 的父视图不是 view而是 view 下面的某个容器视图比如背景层内部再嵌套一层容器这时候 contentView.frame 是相对容器视图的就不能直接和touch.location(in: view)做比较。我见过一类 bug内容卡片长按的时候touch.view变成卡片里的某个 imageView开发者又习惯性地写touch.view contentView判断结果永远返回 false点击卡片里的图片就会把弹窗关掉。正确的思路是“判断触摸点是否落在内容区域”而不是“判断触摸目标是否是 contentView”。坐标位置判断抗嵌套能力强得多建议一律用位置判断。3.3 适配底部弹层与不规则弹窗布局底部弹层的 contentView 通常贴着屏幕底部frame 是一个底部对齐的矩形区域。上面的shouldReceive判断依然成立contentView.frame 包含了底部 360 高度的区域点击这个区域内的事件不会被手势拦截。不规则弹窗比如中间带气泡箭头、四周有阴影的卡片判断逻辑可以进一步精确因为 contentView 是气泡那块的容器阴影如果也在 frame 内点击阴影部分按逻辑也应该算作“内容区域”一般不会触发关闭。如果产品要求“只有看到气泡透明区域内的卡片才算内容”那可以把判断改成touch.view是否属于某个自定义子类或者用精确的 UIBezierPath contains 判断。func gestureRecognizer(_ gestureRecognizer: UIGestureRecognizer, shouldReceive touch: UITouch) - Bool { let point touch.location(in: contentView) return !bubblePath.contains(point) }这里把触摸点先换算到 contentView 坐标系再判断是否在气泡路径内比直接判断 frame 更精细。但注意这种写法性能开销略大复杂路径不要嵌套得太深。3.4 isUserInteractionEnabled 的使用边界在弹窗开发中isUserInteractionEnabled也是一个高频出现的属性。很多人会在 contentView 上设置isUserInteractionEnabled true或者在全屏遮罩 view 上设置 true/false结果行为不对。真相是UIView 的isUserInteractionEnabled默认就是 true。如果你把全屏遮罩 view 的该属性设为 false那么整个 view 和它的所有子视图都会失去交互能力contentView 里的按钮也会一起失灵。如果你只想让“背景区域不接收触摸”正确做法不是关掉交互而是把手势代理的返回条件写对。反过来如果不希望某个纯装饰性的子视图遮挡手势可以在那个子视图上重写point(inside:with:)返回 false让它不参与 hitTest。这种局部关闭交互的思路在弹窗内部嵌套了透明占位视图时非常有用。4. 高频坑位排查实录4.1 点击内容区域弹窗也消失了这是最常见的 bug原因是手势代理判断错误或缺失。排查路径先确认是否使用了方案二但没有实现shouldReceive或者实现了但坐标系弄错了。检查 contentView.frame 是否与触摸点坐标系一致。最容易出错的场景是 contentView 被约束约束在某个子容器里。如果内容区域里有 UITableView、UICollectionView、UIScrollView还需要确认它们不会把手势的触摸事件提前吞掉。一般 UITapGestureRecognizer 和滚动是不会互相干扰的但如果加了 UITapGestureRecognizer 到 contentView 内部要小心与 cell 选中手势冲突。每次遇到“点击内容也关闭弹窗”我最先怀疑的就是“我到底有没有把 delegate 挂到那个手势上”。delegate 是 weak 的如果代理对象被释放shouldReceive不会被调用所有点击都可能触发关闭。4.2 遮罩点击无反应presentedView 尺寸问题方案一中如果点击任何背景区域都没反应先检查frameOfPresentedViewInContainerView是否生效。如果 presentedView 还是全屏遮罩根本接不到触摸。另一个可能性presentedViewController.view 的背景色不是 clear而是白色或者其他不透明色视觉上把遮罩盖住了。这种情况下用户连背景都看不全自然也谈不上点击。检查顺序就两步一看 frame二看 backgroundColor。4.3 手势把列表点击吃掉了如果 contentView 内是一个 UITableView并且你把 UITapGestureRecognizer 添加到了 contentView 或者它的父视图上那么 cell 的 didSelect 有可能被手势拦截。这种情况下处理方式是手势的cancelsTouchesInView设置为 false允许触摸事件继续传给 tableView。在shouldReceive里判断触摸点是否在 tableview 范围内如果在直接返回 false。但还有一个隐藏情况手势加了之后tableview 的 cell 高亮正常点击事件却延迟。这是因为手势识别器默认会延迟触摸派发体验上就是“按钮像被胶水粘住一样”。解决方式也是设cancelsTouchesInView false或者把 shouldReceive 判断做精准一些让内容区域的触摸直接不参与手势。4.4 转场代理被释放导致闪退转场代理保存不当导致崩溃我在真机上遇到过不止一次。现象是弹窗第一次打开正常第二次 present 直接 crash或者自定义转场完全失效变成普通全屏。定位方法很直接在presentationController(forPresented:presenting:source:)方法里加打印看是否每次 present 都会调用。如果只调用一次很可能代理已经被释放。解决方案就是上文中提过的让弹窗控制器本身强持有转场代理对象。注意不要在 viewDidLoad 里重新设置 modalPresentationStyle 和 transitioningDelegate因为初始化时机太晚转场配置要在 present 执行前完成。4.5 连续点击触发了多次 dismiss当用户快速双击遮罩UITapGestureRecognizer 默认只识别第一次轻触第二次如果还在识别范围内会再次触发 dismiss结果可能出现弹窗关闭动画被二次调用的警告。简单防护设置一个isDismissing标志位。private var isDismissing false objc private func handleTapOnDimming(_ sender: UITapGestureRecognizer) { guard !isDismissing else { return } isDismissing true presentedViewController.dismiss(animated: true, completion: nil) }在 dismissal 转场完成或者 viewDidDisappear 里把标志位重置。这个细节在弹窗内需要处理多个辅助动作时尤其重要比如关闭后立即打开另一个弹窗。5. 封装通用弹窗组件的几个关键点5.1 抽象网络协议与样式参数方案一和方案二各写各的时间长了会很乱。我在项目里通常会把弹窗抽象成一个PopupPresentable协议让具体的弹窗控制器遵循protocol PopupPresentable: UIViewController { var preferredPopupSize: CGSize { get } var popupCornerRadius: CGFloat { get } var maskAlpha: CGFloat { get } }PresentationController 子类通过 weak 引用这个协议获取弹窗的尺寸和样式这样弹窗控制器不需要关心 PresentationController 的具体实现。底部弹层则通过一个枚举参数控制布局方式enum PopupLayout { case center(size: CGSize) case bottom(height: CGFloat, margin: CGFloat) case custom(presentedFrame: CGRect) }这个枚举既驱动 UIPresentationController 的 frame 计算也驱动方案二的手势 shouldReceive 判断统一管理会少很多心智负担。5.2 外部设置 contentSize 与圆角样式如果你只是希望某个页面弹一个自定义卡片不想引入复杂的基类体系最少需要暴露的配置是 contentSize 和圆角。final class PopupViewController: UIViewController { var contentSize: CGSize CGSize(width: 300, height: 220) { didSet { updateContentSize() } } var cornerRadius: CGFloat 12 { didSet { updateCorner() } } }在 presentedViewController.view 里用 frame 布局或者 AutoLayout 约束都行。个人偏好用 AutoLayout配合preferredContentSize在 iPad 分屏、横竖屏切换时表现更稳定。5.3 使用 UIViewController 闭包回调与按钮事件弹窗内的确定、取消按钮一般通过闭包回调给外部控制器。我习惯把回调定义为var confirmHandler: (() - Void)? var cancelHandler: (() - Void)?按钮点击后先执行回调再执行 dismiss确保界面状态先刷新。如果回调里要 push 页面或者 present 新页面注意先 dismiss 当前弹窗再执行跳转否则会出现“弹窗还没消失、底层页面已经跳走”的视觉抖动。这里有一个容易被忽略的点如果弹窗里的按钮和遮罩手势都注册在同一个响应链上按钮点击时如果cancelsTouchesInView没处理好遮罩手势可能先识别终止按钮事件。所以凡是内容区域内的手势都建议在 shouldReceive 里尽早返回 false让按钮事件走正常路径。6. 最后分享一个调试思路弹窗事件判断出问题时我一般会在 hitTest 结果上做一次快速定位重写容器 view 的 hitTest 方法打印触摸点和最终命中的 view。这样能直接看到事件到底交给了谁是遮罩还是内容卡片。判断清楚了再改代码比盲目改手势参数高效得多。override func hitTest(_ point: CGPoint, with event: UIEvent?) - UIView? { let view super.hitTest(point, with: event) print(point: \(point), hit: \(String(describing: view))) return view }这个临时调试代码不用上架但排查弹窗事件问题时非常顶用。它可以一次性暴露三种问题改前的命中目标、改后的命中目标、系统默认的命中目标。我个人实际开发中的体会是这类看似简单的小交互往往比复杂功能更容易出“玄学问题”原因在于事件分发链条涉及视图层级、手势识别器、响应者链三层机制。把底层机制想清楚再动手写代码基本可以做到一次成型。