iOS

折叠屏适配

更新时间: 2026/11/18 16:01:29

本文主要介绍 IM UIKit 如何适配折叠屏。

概述

NEAdaptiveUIKit 是 IM UIKit 的自适应呈现外壳,用于折叠屏、宽屏等大屏场景:

窗口宽度 布局形态 说明
Compact 单页 窗口较窄时保持单页呈现
Medium/Expanded 双栏 左侧为列表,右侧为详情栏,并在窗口右侧提供 navigation rail

指责边界:

  • 外壳只依赖 UIKit,负责栏宽、rail 与导航呈现,不接管 SDK、会话订阅或 ViewModel。
  • 宿主提供 消息/通讯录/我的 三个导航栈和一个详情导航栈。
  • 窗口折叠、展开、旋转时,外壳复用已有导航栈与聊天实例。

组件依赖

NEAdaptiveUIKit 由 NEChatUIKit 等组件通过 podspec 自动依赖,接入 IM UIKit 无需单独声明;宿主自行装配外壳时再显式添加:

rubypod 'NEAdaptiveUIKit', '10.9.75'

以源码方式集成时使用本地路径:

rubypod 'NEAdaptiveUIKit', :path => 'NEAdaptiveUIKit/NEAdaptiveUIKit.podspec'

IM UIKit 10.9.75 及以上版本的组件 Pod 只发布在云信 Spec 仓库(Github|Gitee),未上传公共 CocoaPods 仓库,Podfile 需声明其中一个 source。

接入步骤

步骤一:启动门禁

自适应外壳是折叠屏(Duo)专用的可选呈现路径。宿主必须在首次组装根页面时先判断设备形态,再选择唯一容器:

swiftimport NEBaseUIKit

let useAdaptiveUIKit = NEAdaptiveDeviceGate.isFoldableDevice
if useAdaptiveUIKit {
  window.rootViewController = makeAdaptiveShell()
} else {
  window.rootViewController = makeLegacyTabBarController()
}
  • NEAdaptiveDeviceGate.isFoldableDevice 的几何判定只认可折叠屏的 侧边控件区:横向安全区仅在单侧存在,且存在贴边缘的竖向窄条遮挡区。普通 iPhone 的刘海、灵动岛、状态栏都是横向条,横屏刘海机型的左右安全区对称,都不会命中。。
  • 请勿将 遮挡区非空 当作折叠屏证据,否则普通机型会误入双栏外壳。
  • 门禁要在启动组装根页面时生效,不能等用户点击通讯录或会话后再切换容器。
  • 装配外壳后请设置 NEAdaptiveDeviceGate.isAdaptiveHostActive = true:页面读取该能力标记决定尺寸,不再按机型判断;未显式设置的宿主回退到 isFoldableDevice。

步骤二:创建外壳

swiftimport NEAdaptiveUIKit

let configuration = NEAdaptiveShellConfiguration(
  railWidth: 72, singleContentMinimumWidth: 240,
  masterMinimumWidth: 240, detailMinimumWidth: 320,
  dividerWidth: 1, mediumMasterWidth: 280,
  expandedMasterWidth: 320, masterMaximumWidth: 360
)
configuration.railUsesTrailingEdge = true
configuration.railItemsBottomInset = 12

let shell = NEAdaptiveShellViewController(
  sections: [messagesNavigation, contactsNavigation, mineNavigation],
  detailNavigationController: chatNavigation,
  configuration: configuration
)
window.rootViewController = shell

参数说明:

参数 说明
sections 左侧分区(消息/通讯录/我的)的导航控制器数组
detailNavigationController 右侧详情栏导航控制器
configuration 尺寸与样式配置,示例数值取自示例工程,接入时按实际窗口标定

步骤三:会话呈现

会话点击的最终呈现点交给 conversationCoordinator,复用原有路由参数与聊天初始化入口:

swiftshell.conversationCoordinator.controllerFactory = { intent in
  // 不在这里查询或修改 SDK 状态,只负责创建页面。
  existingChatFactory(intent.route, intent.parameters)
}

也可以直接调用外壳方法接管单次打开:

swiftlet intent = NEConversationOpenIntent(
  key: conversationId,
  route: "imkit://chat/p2p.page",
  parameters: ["anchor": anchorMessage as Any]
)
if !shell.openConversation(intent) {
  // 外壳未接管时执行原路由
}

步骤四:子页面呈现

通讯录、我的等根导航在执行原 push 前调用公开入口:

swiftif !shell.presentSectionChild(child, from: sectionNavigation, animated: true) {
  sectionNavigation.pushViewController(child, animated: true)
}

返回值含义:

返回值 含义 调用方处理
true 页面已在右侧详情栏呈现 不再 push
false Compact 或旧布局 继续原导航

详情中的更深层页面沿用自己的导航栈。

步骤五:侧栏刷新与自绘标题栏

场景 处理方式
自定义导航栏文案或启用态变化 调用 shell.refreshRailNavigation() 刷新侧栏
侧栏返回入口识别 按类名识别 NEUnifiedBackButton
收起入口识别 按 id.arrowDown 识别
右侧操作识别 按 id.sureButton/id.multiSelect/id.adaptiveAction 识别
列内 present 页面出现或消失 监听 NENotificationName.adaptivePresentationDidChange,据此重解析侧栏
无标题栏的 push 页面 导航栈深大于 1 时,侧栏自动补返回入口并执行 pop

布局与侧栏规则

各模式布局:

模式 布局表现
Compact 单页呈现,聊天输入区贴底;从聊天返回列表后右列回到空占位,再次打开会重新创建会话页面
Medium/Expanded 左列列表 + 右列详情;通讯录与「我的」从首次显示起就保持左侧根页面与右侧空详情,无需先点开子页面;返回根页面时清空右侧详情,双栏仍保留

navigation rail 规则:

  • 位于窗口右侧(railUsesTrailingEdge = true)。
  • 返回入口在顶部,页面右侧操作在其下方,消息/通讯录/我的入口组固定在侧栏底部。
  • 返回与右侧操作统一为圆形控件(浅色底 + 细描边);页面右侧按钮文案中的计数(如「确定(10)」)拆为角标显示。

present 页面与兜底:

场景 行为
列内 present 页面(.overCurrentContext 等) 纳入侧栏承载链:顶层返回/右侧操作迁移到侧栏,底层页面入口保持隐藏
UIAlertController、pageSheet、全屏等遮挡型呈现 不改写侧栏状态
窗口可用宽高不足 外壳回退到宿主原有布局,并回调 onLegacyFallback

配置项

NEAdaptiveShellConfiguration 的关键配置如下:

属性 类型 说明
railWidth/railItemHeight/railItemSpacing CGFloat 侧栏宽度、分区入口单项高度与间距
railUsesTrailingEdge Bool 侧栏贴窗口物理右侧边缘,折叠屏建议开启
railItemsBottomInset CGFloat 分区入口组与窗口底部安全区的距离
railBackButtonSize/railActionButtonSize CGFloat 侧栏返回按钮、右侧操作按钮的尺寸
railActionSpacing/railActionTopSpacing CGFloat 右侧操作之间、返回与首个操作之间的间距
railBackTopInset CGFloat 侧栏返回入口相对尾部系统状态区的偏移,由宿主按窗口标定
railControlBackgroundColor/railControlBorderColor/railControlBorderWidth UIColor/UIColor/CGFloat 侧栏圆形控件的底色、描边色与描边宽度
railActionTextColor/railActionTextFont UIColor/UIFont 右侧操作文字颜色与字体
railBadgeBackgroundColor/railBadgeTextColor UIColor?/UIColor 数量角标背景色(nil 时跟随主题色)与文字颜色
railBackgroundColor/dividerColor/selectedTintColor/normalTintColor UIColor 侧栏背景、分栏分隔线、选中与未选中态颜色
usesSystemBackButtonStyle/backImage/backTintColor/backAccessibilityLabel Bool/UIImage?/UIColor/String? 返回按钮样式;关闭系统样式时使用皮肤返回图
mediumThreshold/expandedThreshold/compactAspectRatio CGFloat 中/宽窗口判定阈值与紧凑比例
singleContentMinimumWidth/masterMinimumWidth/detailMinimumWidth/masterMaximumWidth CGFloat 单列、主列、详情列的最小与最大宽度
mediumMasterWidth/expandedMasterWidth/dividerWidth CGFloat 中/宽窗口主列宽度与分栏宽度
contentTopInset/contentBackgroundColor CGFloat/UIColor 内容区顶部留白与背景色

railItemsTopInset 已废弃:分区入口组固定在侧栏底部,不再读取顶部内边距。

关键类型

类型 说明
NEAdaptiveShellViewController 外壳控制器。init(sections:detailNavigationController:configuration:);presentSectionChild(_:from:animated:)、openConversation(_:)、selectSection(_:)、showConversationList()、refreshRailNavigation()、detachSectionsForLegacyTransfer();回调 onSectionSelected、onConversationOpened、onCompactChatVisibilityChanged、onLegacyFallback、onContentLayout
NEAdaptiveShellConfiguration 列宽、阈值、侧栏与控件样式配置
NEChatDetailHostController 右侧详情栏容器
NEConversationNavigationCoordinator 详情栏会话导航:controllerFactory、presentationAction、open(_:)、showPlaceholder(_:)、reset()
NEConversationOpenIntent 打开会话的意图:key、route、parameters、requiresPresentationAction
NEAdaptiveWindowContext/NEWindowSnapshot 窗口尺寸与安全区采样;快照包含 displayScale 与 reservedRegions(激活的 division/occlusion 占位区)
NEAdaptiveLayoutPolicy 无状态布局策略,resolve(window:configuration:) 返回 NEAdaptiveLayoutDecision(mode 为 compact/medium/expanded,并给出各列宽度)
NEAdaptiveDeviceGate 设备门禁:isFoldableDevice、isAdaptiveHostActive
NEAdaptiveBottomSheetController 列内底部弹层,位于 NEBaseUIKit

注意事项

  • 普通 iPhone、iPad 与普通模拟器必须继续使用原有 Tab 与 push 结构,不要启用外壳。
  • 外壳不接管 SDK、会话订阅与 ViewModel;未读订阅仍由宿主或原组件负责。
  • 自定义路由应使用自己的 controllerFactory,不要在列表的 onOpenConversation 前置 hook 中无条件调用标准 factory。
  • 视图层级与栏宽属于外壳职责,页面内部不要再次根据机型计算宽度。
此文档是否对你有帮助?
有帮助
去反馈
  • 概述
  • 组件依赖
  • 接入步骤
  • 步骤一:启动门禁
  • 步骤二:创建外壳
  • 步骤三:会话呈现
  • 步骤四:子页面呈现
  • 步骤五:侧栏刷新与自绘标题栏
  • 布局与侧栏规则
  • 配置项
  • 关键类型
  • 注意事项