iOS 输入框键盘遮挡的 8 类问题逐条排查附源码行号【免费下载链接】IQKeyboardManagerCodeless drop-in universal library allows to prevent issues of keyboard sliding up and cover UITextField/UITextView. Neither need to write any code nor any setup required and much more.项目地址: https://gitcode.com/gh_mirrors/iq/IQKeyboardManager一条用户反馈收件人表单页点地址框整页被键盘顶起、导航栏被盖住另一台设备上点输入框毫无反应placeholder 完全藏在键盘后面。打开调试日志控制台只输出一行Need to move: 0.0。两种现象根因相同IQKeyboardManager 的键盘遮挡避让没有按预期工作。本文按 5 种界面容器把 8 类常见偏移问题逐条过一遍配置项都标注到源码文件和行号。项目一句话定位IQKeyboardManager 是一个免写代码的 iOS 键盘遮挡避让库一行代码启用后它替你移动页面、滚动列表、调整 contentInset保证 UITextField 和 UITextView 不被键盘盖住不需要手算 frame、不需要写子类。Swift 版本要求 iOS 13GitHub star 数长期在 4 万 量级8.x 仍在迭代当前仓库 Package.swift 依赖 IQKeyboardToolbarManager 1.1.4、IQTextView 1.0.5ObjC 版本已拆到独立仓库。本文覆盖验证接入是否真正生效给出一行日志确认法按列表 / 滚动 / 弹窗 / 全屏 / 嵌套 5 种容器定位偏移根因配置距离与排除项keyboardDistance、disabledDistanceHandlingClasses附取值区间读懂 7.x → 8.x 迁移表修掉 3 个高频编译报错输出一份可直接贴进发版前自查的 8 项清单5 行代码接入并确认它真的在跑// AppDelegate主开关 全局距离 调试日志三行足够IQKeyboardManager.shared.isEnabled true IQKeyboardManager.shared.keyboardDistance 15.0 IQKeyboardManager.shared.isDebuggingEnabled true定义位于 IQKeyboardManager.swiftisEnabled 默认值 false需显式开启keyboardDistance 位于 第 112 行默认值 10.0最小值 0负值只输出警告isDebuggingEnabled 位于 IQKeyboardManagerDebug.swift默认值 false官方示例同样这样打开AppDelegate.swift 第 39 行。推荐起步参数keyboardDistance建议 10–20pt过小输入框贴键盘过大页面被推得过高。单个输入框要例外时用textField.iq.distanceFromKeyboard 50.0定义在第 82 行默认值UIView.defaultKeyboardDistance含义是跟随全局设置。layoutIfNeededOnUpdate默认 false第 127 行页面跟着键盘动画抖动时先试切换这一项。生效确认键盘弹出后控制台会输出Enabled和Need to move: 数值后者就是本轮计算出的偏移量正数表示输入框被挡、需要上移IQKeyboardManagerPosition.swift 第 176 行。看到数值非零、输入框确实上移才说明接入真正在工作。按五种容器逐一定位偏移原因列表容器UITableViewController 子类页面不响应键盘避让的修法典型表现页面继承 UITableViewController键盘弹起后毫无反应输入框留在键盘后面。原因很直接——类级排除生效了。// 1. 确认控制器类是否在排除列表里 print(IQKeyboardManager.shared.disabledDistanceHandlingClasses) // 2. 确需恢复时少见把 UITableViewController 从排除列表移除 IQKeyboardManager.shared.disabledDistanceHandlingClasses.removeAll { $0 UITableViewController.self }定义位于 IQKeyboardManager.swiftdisabledDistanceHandlingClasses 默认值 3 项[UITableViewController.self, UIInputViewController.self, UIAlertController.self]同一类同时出现在 enabledDistanceHandlingClasses 时排除优先。常规路径UIViewController UITableView下库不会推整页而是滚动列表并调整底部 contentInset。对 cell 复用场景有专门补偿当前行显示不全时先算上一行 cell 应滚到多少位置再取较小值滚动。出处IQKeyboardManagerPosition.swifthandleTableViewCaseUICollectionView 对应 第 512 行。滚动容器UIScrollView 的偏移被顺手改掉又还原不回去典型表现键盘弹出后 scrollView 的 contentOffset / contentInset 被修改收起键盘后滚动位置停在原地用户得手动滚回去。// 跳过这个 scrollView 的滚动调整 scrollView.iq.ignoreScrollingAdjustment true // 或只停止修改它的 contentInset scrollView.iq.ignoreContentInsetAdjustment true // 键盘收起后把这个 scrollView 的 contentOffset 还原回键盘弹起前的值 scrollView.iq.restoreContentOffset true定义位于 UIScrollViewIQKeyboardManagerExtension.swift三个属性默认值均为 falserestoreContentOffset 位于 第 80 行默认值 false。库是怎么找到目标 scrollView 的从输入框的 superview 沿链条向上找取第一个isScrollEnabled true且ignoreScrollingAdjustment false的 UIScrollView中间某层容器关闭了滚动就继续往上找。你看到的偏移若是这条遍历找错了容器给那层容器设ignoreScrollingAdjustment true即可解决。出处IQKeyboardManagerPosition.swift。模态 / 弹层内的输入框默认被排除要自己接管典型表现UIAlertController 或自定义弹层里的输入框键盘弹出后要么把整个根视图顶起来背景页面跟着动要么完全不动。// 弹层内输入框强制关闭全局管理改由弹层自己的 scrollView 处理 alertTextField.iq.enableMode .disabled // 打开点按外部收起键盘默认关闭 IQKeyboardManager.shared.resignOnTouchOutside true // 把自定义视图加入手势忽略列表避免弹层内按钮被收起手势抢走 IQKeyboardManager.shared.touchResignedGestureIgnoreClasses.append(MyCardView.self)定义位于 UIViewIQKeyboardManagerExtension.swiftenableMode 默认值.default跟随全局开关resignOnTouchOutside 位于 IQKeyboardManagerResign.swift默认值 false。⚠️ UIAlertController 同时出现在距离排除列表和点按收起的排除列表里后者默认[UIAlertController.self, UIInputViewController.self]IQKeyboardResignHandler.swift 第 55 行。弹层内输入框建议 enableMode 弹层内滚动自己接管别指望全局逻辑。全屏 / 边缘延伸布局键盘盖住导航栏怎么办典型表现edgesForExtendedLayout设成.all或.bottom页面延伸到底部安全区键盘弹出后偏移量不对甚至盖住导航栏。// 官方示例演示延伸到边缘的页面全屏模式 override func viewDidLoad() { super.viewDidLoad() self.edgesForExtendedLayout .all }定义位于 EdgesForExtendedLayoutViewController.swift示例显式设为.alledgesForExtendedLayout 的默认值由 UIKit 控制。库的位置计算已经把底部 safe area 从键盘高度里减掉IQKeyboardManagerPosition.swift 第 283 行并以导航栏高度无导航栏时为状态栏高度作为上边界第 299 行。所以这个场景的偏移多半来自你手动的 safe area inset或对根视图 origin 的自定义动画在跟库抢位置。嵌套容器自定义视图层级下调整不生效典型表现输入框嵌在 stack view、自定义容器或 collection view 的 supplementary view 里程序化改完布局后位置不更新或偏移量不对。// 程序化修改 frame / 约束后手动触发一次位置计算 IQKeyboardManager.shared.reloadLayoutIfNeeded() // 检查输入框链条上是否存在可滚动的祖先 print(String(describing: textField.iq.superviewOf(type: UIScrollView.self)))定义位于 IQKeyboardManager.swiftreloadLayoutIfNeeded 仅在 isEnabled、键盘可见且根视图配置就绪时生效superviewOf 为 UIViewParent.swift 的同类型祖先查找。还有一种定位办法给实际移动量挂回调和期望值对一下// 每次偏移变化打印实际上移量便于核对 IQKeyboardManager.shared.movedDistanceChanged { moved in print(moved: \(moved)) }定义位于 IQKeyboardManagerPosition.swiftmovedDistance 默认值 0。7.x 升 8.x 版本差异速查旧 API7.x新 API8.x影响点是否破坏性变更enableAutoToolbar默认 trueIQKeyboardToolbarManager.shared.isEnabled键盘上方工具栏是默认改为 false旧属性标废弃IQPreviousNextViewIQDeepResponderContainerView前后切换按钮容器是类不可用IQKeyboardReturnKeyHandlerIQKeyboardReturnManager独立库返回键处理是类不可用keyboardDistanceFromTextFieldkeyboardDistance全局键盘距离是重命名resignOnTouchOutsideAPI 名不变拆入 Resign subspec点按外部收起否仅拆分完整迁移清单含工具栏属性、类重命名明细Documentation/MIGRATION GUIDE 7.0 TO 8.0.md。三个最高频编译报错keyboardDistanceFromTextField is unavailable, renamed to keyboardDistance→ 改用IQKeyboardManager.shared.keyboardDistance废弃声明见 IQKeyboardManagerDeprecated.swift 第 33 行。IQPreviousNextView is unavailable: renamed to IQDeepResponderContainerView→ Storyboard 里自定义视图的类名和模块都改成 IQKeyboardToolbarManager声明 第 88 行。registerKeyboardSizeChange is unavailable→ 改用 IQKeyboardNotification 独立库声明 第 63 行。自查清单IQKeyboardManager.shared.isEnabled true默认 false不设等于没开第 72 行isDebuggingEnabled true键盘弹出时控制台出现EnabledNeed to move:数值非零且量级等于期望偏移当前控制器类不在disabledDistanceHandlingClasses里默认 3 项含 UITableViewController输入框的iq.enableMode没被别的代码设成.disabledscrollView 的iq.ignoreScrollingAdjustment/iq.ignoreContentInsetAdjustment没被误设 true没有自管的 safe area inset / 根视图 origin 动画在和库抢位置程序化改过布局后调用过reloadLayoutIfNeeded()生产环境补充按需启停与 3 个边缘 case按需启停。README 明确警告与第三方键盘 UI 冲突时由开发者负责切换README.md 第 91 行// 展示第三方输入组件期间关闭dismiss 后恢复 IQKeyboardManager.shared【免费下载链接】IQKeyboardManagerCodeless drop-in universal library allows to prevent issues of keyboard sliding up and cover UITextField/UITextView. Neither need to write any code nor any setup required and much more.项目地址: https://gitcode.com/gh_mirrors/iq/IQKeyboardManager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
