折叠屏适配
更新时间: 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。 - 视图层级与栏宽属于外壳职责,页面内部不要再次根据机型计算宽度。
此文档是否对你有帮助?




