企业官网建设流程全解析

在 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 两种主流方案的选型对比

我实际用过两类方案，各有适用场景，先给结论：

如果你要写的是居中卡片式弹窗，比如抽奖、公告、优惠券详情，方案一是首选。如果你要写的是底部弹层、筛选面板、菜单选择器，方案二更顺手。下面两个方案我分别展开，代码可以直接抄。

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 限定内容尺寸

为什么这步很关键？因为如果不重写 frameOfPresentedViewInContainerView，presentedView 默认会是 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 上添加的 UITapGestureRecognizer，target 直接指向handleTapOnDimming，手势一旦识别就调用presentedViewController.dismiss(animated:completion:)。

这里有一个底层机制值得理解：UITapGestureRecognizer 添加到 dimmingView 上之后，系统只会在“触摸命中 dimmingView 本身或其子视图”时去判断手势。dimmingView 在 containerView 的 index 0，presentedView 在 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是必须的。如果忘了设置，默认可能是 pageSheet，presentedViewController.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 }

这个临时调试代码不用上架，但排查弹窗事件问题时非常顶用。它可以一次性暴露三种问题：改前的命中目标、改后的命中目标、系统默认的命中目标。

我个人实际开发中的体会是，这类看似简单的小交互，往往比复杂功能更容易出“玄学问题”，原因在于事件分发链条涉及视图层级、手势识别器、响应者链三层机制。把底层机制想清楚，再动手写代码，基本可以做到一次成型。