tvOS应用中网格键盘在搜索结果获焦时无法滑动的问题

问题详情 #

• 基于UIKit开发tvOS 15应用，使用UISearchController时出现布局异常：当系统设置选择网格键盘（设置->通用->键盘布局），搜索结果视图获焦后，键盘无法滑至屏幕边缘让搜索结果占满可用宽度（Apple官方应用的标准行为），而是保持原位遮挡部分搜索结果区域。
• 已严格遵循WWDC20视频《Discover search suggestions for Apple TV》的实现步骤：
  • 将UISearchController嵌入UISearchContainerViewController，且标签栏控制器嵌套在UINavigationController中
  • 在搜索结果控制器中使用setContentScrollView(_:)指定要观察的集合视图（已弃用searchControllerObservedScrollView）
• 问题在模拟器、Apple TV 4K（第二代）、Apple TV HD设备上均能复现
• YouTube、Spotify等第三方应用可正常实现该键盘靠边行为，但不确定其底层是否使用UIKit或TVMLKit
• 已通过Apple开发者论坛提问、Feedback Assistant提交Bug两个月，未收到官方回复

排查与解决方向 #

• 校验导航层级结构
  确保UISearchContainerViewController的嵌入层级正确，避免多层嵌套（如多次嵌套UINavigationController）导致布局逻辑冲突。可尝试简化导航结构，直接将UISearchContainerViewController作为UINavigationController的根视图进行测试。
• 检查搜索结果视图的约束设置
  确认搜索结果控制器的集合视图已设置全屏约束：leading、trailing、top、bottom均绑定到父视图边缘，无额外内边距或宽度限制约束。
• 手动触发布局更新
  在搜索结果视图获焦的回调（如didUpdateFocus(in:with:)）或viewDidAppear中，调用setNeedsLayout()和layoutIfNeeded()，强制系统重新计算键盘与内容视图的布局关系。
• 确认setContentScrollView(_:)的调用时机
  确保该方法在搜索结果控制器的viewDidLoad或viewWillAppear中调用，且传入的集合视图是直接负责内容滚动的主视图，未被其他容器视图包裹导致系统无法监听滚动事件。
• 自定义键盘避让逻辑
  若上述方法无效，可通过监听UIKeyboardWillChangeFrameNotification通知，手动调整搜索结果视图的宽度和位置：
  1. 监听键盘帧变化通知
  2. 判断当前键盘是否为网格布局
  3. 根据键盘的最终位置，调整搜索结果视图的trailing约束，让内容占满剩余屏幕宽度

临时Workaround #

若官方Bug未修复，可临时采用以下方案：

• 在搜索界面添加提示，引导用户切换至默认键盘布局
• 针对网格键盘模式，主动缩小搜索结果视图宽度以适配键盘位置（会牺牲部分体验，仅作为应急方案）

内容的提问来源于stack exchange，提问作者Woody