Keyboard Avoidance — 本质、实现方法及界面偏移

什么是 Keyboard Avoidance

Keyboard Avoidance — 是一组技术，确保在 iOS 系统键盘出现时活动输入字段的可见性。基本问题：键盘占用高达 50% 的屏幕，覆盖了界面的下半部分，包括文本字段、发送按钮和其他元素。

实现方式有三种主要方法：通过 Keyboard Notifications 手动管理（经典方法，从 iOS 3.0 开始可用），使用带有自动滚动的 UIScrollView（Apple 推荐），以及 Keyboard Layout Guide（iOS 15+ 的现代方法）。选择取决于最低支持的 iOS 版本和界面的复杂性。

根据 Apple 的说法，如果文本字段完全被键盘覆盖，缺少 Keyboard Avoidance 是应用程序在审核时被拒绝的最常见原因之一。App Store 指南明确要求所有交互元素在活跃输入期间保持可访问。

为什么 iOS 不自动执行此操作

iOS 无法自动确定哪些元素应保持可见，因为它不了解界面的语义。在只有一个文本字段的简单表单中，只需移动整个屏幕即可。在具有自定义面板、浮动按钮和多个部分的复杂界面中，需要不同的行为逻辑。

此外，某些应用程序故意不偏移内容——例如，键盘计算器或编辑器，其中键盘是工作区的一部分。iOS 将决定权留给开发者，为每种场景提供灵活的 API。

Keyboard Frame Notifications

UIKeyboardWillShowNotification — 是 iOS 在键盘出现之前发送的主要通知。它在 UIResponder.keyboardFrameEndUserInfoKey 字典中包含带有键盘最终位置的 CGRect，以及在 UIResponder.keyboardAnimationDurationUserInfoKey 中的动画持续时间。

通知处理程序必须计算活动文本字段和键盘之间的重叠，然后更改容器的下边距（contentInset 或 frame）。如果字段位于键盘上边缘下方，则内容将向上偏移重叠量。当键盘隐藏时，边距将恢复到原始值。

@objc func keyboardWillShow(_ notification: Notification) {
    guard let keyboardFrame = notification
        .userInfo?[UIResponder.keyboardFrameEndUserInfoKey]
        as? CGRect else { return }
    
    let keyboardHeight = keyboardFrame.height
    scrollView.contentInset.bottom = keyboardHeight
    scrollView.verticalScrollIndicatorInsets.bottom = keyboardHeight
}

使用通知时，重要的是将动画与系统键盘同步。iOS 传递动画曲线（UIResponder.keyboardAnimationCurveUserInfoKey）和持续时间。使用带有这些参数的 UIView.animate，使内容随着键盘的显示而平滑地移动。

iOS 15+ 中的 Keyboard Layout Guide

UIScrollView.keyboardLayoutGuide — 是 iOS 15 中引入的用于 Keyboard Avoidance 的现代 API。它自动跟踪键盘的位置，并更新将界面底部连接到键盘上边缘的 Auto Layout 约束。

使用时，只需在 UIScrollView 或 UIStackView 中激活布局指南，并将内容的底部约束链接到它。无需手动处理通知、高度计算和动画——系统会自动完成所有操作，将动画与键盘的显示和隐藏同步。

// 启用键盘布局指南 (iOS 15+)
scrollView.keyboardLayoutGuide.followsUndockedKeyboard = true

// 将底部约束固定到键盘顶部
contentView.bottomAnchor.constraint(
    equalTo: scrollView.keyboardLayoutGuide.topAnchor
).isActive = true

followsUndockedKeyboard — 确定指南是否应对可能从底部边缘分离的键盘（在 iPad 上）做出反应的属性。仅当界面与浮动键盘正常工作时才设置为 true。对于 iPhone，此属性被忽略——键盘始终连接到底部边缘。

UIScrollView 和键盘

UIScrollView — 是 Apple 推荐作为 Keyboard Avoidance 基础的容器。当键盘出现时，滚动视图会增加其 contentInset.bottom，允许将内容向上滚动并使活动字段可见。

关键方法是 scrollRectToVisible，它以编程方式滚动滚动视图，使指定的矩形（活动文本字段）位于可见区域。通过将 contentInset 的更改与 scrollRectToVisible 的调用相结合，您可以确保该字段不仅未被覆盖，而且位于可见区域的顶部。

func adjustScrollForKeyboard(
    keyboardHeight: CGFloat,
    activeField: UIView
) {
    scrollView.contentInset.bottom = keyboardHeight
    scrollView.verticalScrollIndicatorInsets.bottom = keyboardHeight
    
    var visibleRect = view.frame
    visibleRect.size.height -= keyboardHeight
    
    if activeField.frame.origin.y > visibleRect.maxY {
        scrollView.scrollRectToVisible(
            activeField.frame, animated: true
        )
    }
}

对于带有 UITableView 的 UIViewController，Apple 建议使用 UITableViewController，它会在键盘出现时自动调整 contentInset。如果您使用带有添加表格的 UIViewController，则必须手动实现 Keyboard Avoidance——UITableViewController 不会为自定义控制器提供此行为。

Auto Layout 和 Keyboard Avoidance

Auto Layout 允许在不编写动画代码的情况下实现 Keyboard Avoidance——只需更改特定约束的活动状态（isActive）或响应键盘通知更新其常量即可。

典型方案：为滚动视图或内容的底部边距创建一个 IBOutlet NSLayoutConstraint，在 keyboardWillShow 处理程序中设置 constraint.constant = keyboardHeight，并在 keyboardWillHide 中重置为 0。通过 animate 块内的 layoutIfNeeded 更新布局以实现平滑过渡。

使用 UIStackView 时，更改底部边距约束同样有效：堆栈视图会自动重新分配子元素。但是，如果堆栈视图位于 UIScrollView 内部，则最好管理滚动视图本身的 contentInset，而不是其中的约束。

Keyboard Avoidance 的第三方解决方案

IQKeyboardManager — 是最流行的库（在 GitHub 上拥有超过 16,000 颗星），它可以在控制器中无需一行代码即可实现自动 Keyboard Avoidance。它使用方法交换来跟踪文本字段，并在键盘出现时自动提升内容。

该库提供灵活的设置：您可以指定字段和键盘之间的距离，为单个控制器启用/禁用，配置 UITextView 和自定义输入视图的行为。但是，方法交换可能与其他库冲突，由于不可预测的副作用，Apple 不建议将此方法用于生产代码。

替代方案包括 TPKeyboardAvoiding（轻量级库，约 2000 颗星）和来自社区的 KeyboardManager。对于现代项目，Apple 建议使用 iOS 15+ 的内置工具，对于最低版本较低的项目，则使用带有 contentInset 的 UIScrollView，这是最可靠的内置解决方案。