折叠屏适配
更新时间: 2026/11/18 17:07:48
本文主要介绍 IM OC UIKit 如何适配折叠屏。
概述
自 OC V10.9.30 版本起折叠屏的适配。NEAdaptiveUIKitOC 是 IM UIKit 的自适应呈现外壳,用于折叠屏、宽屏等大屏场景:
| 窗口宽度 | 布局形态 | 说明 |
|---|---|---|
| Compact | 单页 | 窗口较窄时保持单页呈现 |
| Medium/Expanded | 双栏 | 左侧为列表,右侧为详情栏,并在窗口右侧提供 navigation rail |
指责边界:
- 外壳只依赖 Foundation/UIKit,负责栏宽、rail 与导航呈现,不接管 SDK、会话订阅或 ViewModel。
- 宿主提供 消息/通讯录/我的 三个导航栈和一个详情导航栈。
- 窗口折叠、展开、旋转时,外壳复用已有导航栈与聊天实例。
组件依赖
NEAdaptiveUIKitOC 是独立 Pod,NEChatUIKitOC 等组件不会通过 podspec 自动依赖,需要折叠屏能力时在 Podfile 中显式添加:
rubypod 'NEAdaptiveUIKitOC', '10.9.30'
以源码方式集成时使用本地路径:
rubypod 'NEAdaptiveUIKitOC', :path => 'NEAdaptiveUIKitOC/NEAdaptiveUIKitOC.podspec'
- IM OC UIKit 10.9.30 版本组件已发布到公共 CocoaPods 仓库,Podfile 使用默认
source即可。 NEAdaptiveUIKitOC只依赖 Foundation/UIKit,也不需要单独引入NEChatKit。它虽然提供NOS/NOS_Special/FCS/FCS_Special子规格,但四个子规格都指向同一个 xcframework 且没有额外依赖,直接按pod 'NEAdaptiveUIKitOC', '10.9.30'引入默认子规格即可。- 列内底部弹窗基类
NEAdaptiveBottomSheetController位于NEBaseUIKitOC(要被NECustomActionSheetController等基础弹窗继承),外壳只通过NEAdaptiveOverlayDidPresent/NEAdaptiveOverlayDidDismiss两个通知名与基础层协作。
接入步骤
步骤一:启动门禁
自适应外壳是折叠屏(Duo)专用的可选呈现路径。宿主必须在首次组装根页面时先判断设备形态,再选择唯一容器:
objective-c#import <NEBaseUIKitOC/NEBaseUIKitOC.h>
BOOL useAdaptiveUIKit = [NEAdaptiveDeviceGate isFoldableDevice];
if (useAdaptiveUIKit) {
[NEAdaptiveDeviceGate setAdaptiveHostActive:YES];
self.window.rootViewController = [self makeAdaptiveShell];
} else {
self.window.rootViewController = [self makeLegacyTabBarController];
}
NEBaseUIKitOC中NEAdaptiveDeviceGate.isFoldableDevice的几何判定只认可折叠屏的 侧边控件区:横向安全区仅在单侧存在,且存在贴边缘的竖向窄条遮挡区。普通 iPhone 的刘海、灵动岛、状态栏都是横向条,横屏刘海机型的左右安全区对称,都不会命中。。- 请勿将 遮挡区非空 当作折叠屏证据,否则普通机型会误入双栏外壳。
- 门禁要在启动组装根页面时生效,不能等用户点击通讯录或会话后再切换容器。
- 装配外壳后请设置
[NEAdaptiveDeviceGate setAdaptiveHostActive:YES]:页面读取该能力标记决定尺寸,不再按机型判断;未显式设置的宿主回退到isFoldableDevice。 - 场景几何判定使用 iOS 27.1 起的 reserved region API,低版本系统自动退回机型判定(
iPhone19,4,模拟器只认SIMULATOR_MODEL_IDENTIFIER)。 - 建议保留
disableAdaptiveUIKit回滚开关,关闭后不创建 shell、不装 rail、不执行折叠分支。
步骤二:创建外壳
objective-c#import <NEAdaptiveUIKitOC/NEAdaptiveUIKitOC.h>
NEAdaptiveShellConfiguration *configuration =
[[NEAdaptiveShellConfiguration alloc] initWithRailWidth:72
singleContentMinimumWidth:240
masterMinimumWidth:240
detailMinimumWidth:320
dividerWidth:1
mediumMasterWidth:280
expandedMasterWidth:320
masterMaximumWidth:360];
configuration.railUsesTrailingEdge = YES;
configuration.selectedTintColor = <皮肤主题色>;
configuration.normalTintColor = <皮肤次要色>;
configuration.backTintColor = <皮肤文本色>;
configuration.contentBackgroundColor = <页面底色>;
configuration.railControlBackgroundColor = <控件底色>;
configuration.railControlBorderColor = <描边色>;
configuration.railActionTextColor = <主文本色>;
configuration.railBadgeBackgroundColor = <角标底色>;
UINavigationController *detailNavigation =
[[NENavigationController alloc] initWithRootViewController:makeEmptyDetail()];
NEAdaptiveShellViewController *shell =
[[NEAdaptiveShellViewController alloc] initWithSections:@[ messagesNavigation, contactsNavigation, mineNavigation ]
detailNavigationController:detailNavigation
configuration:configuration];
self.window.rootViewController = shell;
参数说明:
| 参数 | 说明 |
|---|---|
sections |
左侧分区(消息/通讯录/我的)的导航控制器数组,顺序即 rail 顺序 |
detailNavigationController |
右侧详情栏导航控制器,栈底放当前皮肤的空态页 |
configuration |
尺寸与样式配置,示例数值取自示例工程,接入时按实际窗口标定 |
- 分区图标、标题、badge 全部取各自
tabBarItem,不要新建未读订阅。 - 外壳自己采集窗口、安全区、trait 和尺寸变化;Scene 更新时调用
[shell refreshWindow]。 - 退出或换根时调用
[shell invalidateWindowContext],并解绑所有 handler。 - 切换根容器时先
[shell detachSectionsForLegacyTransfer]取回分区导航栈。
步骤三:会话呈现
会话点击的最终呈现点交给 conversationCoordinator,复用原有路由参数与聊天初始化入口:
objective-c#import <NEAdaptiveUIKitOC/NEAdaptiveUIKitOC.h>
#import <NEChatUIKitOC/NEBaseChatRouter.h>
shell.conversationCoordinator.controllerFactory = ^UIViewController *(NEConversationOpenIntent *intent) {
// 不在这里查询或修改 SDK 状态,只负责创建页面。
return existingChatFactory(intent.route, intent.parameters);
};
shell.conversationCoordinator.presentationAction = ^BOOL(NEConversationOpenIntent *intent, UIViewController *root) {
// 定位历史消息 / 恢复会话:在保留的 root 上执行原方法。
return [ChatRouter applyPresentationParameters:intent.parameters toViewController:root reload:NO];
};
列表侧通过 onOpenConversation 接管单次打开,openConversation: 返回 NO 时继续执行原路由:
objective-c#import <NIMSDK/NIMSDK.h>
self.conversationController.onOpenConversation = ^BOOL(NSString *route, NSDictionary<NSString *, id> *parameters) {
NSString *conversationId =
[parameters[@"conversationId"] isKindOfClass:NSString.class] ? parameters[@"conversationId"] : @"";
NSString *sessionId =
[parameters[@"sessionId"] isKindOfClass:NSString.class] ? parameters[@"sessionId"] : @"";
BOOL hasAction = [parameters[@"anchor"] isKindOfClass:V2NIMMessage.class] ||
parameters[@"onReceiveNewMsgs"] != nil;
NEConversationOpenIntent *intent = [[NEConversationOpenIntent alloc]
initWithKey:[NSString stringWithFormat:@"%@|%@|%@", route, conversationId, sessionId]
route:route
parameters:parameters
requiresPresentationAction:hasAction];
return [shell openConversation:intent];
};
聊天路由侧同样接上呈现边界(外壳需弱引用):
objective-c__weak NEAdaptiveShellViewController *weakShell = shell;
[ChatRouter setConversationPresentationHandler:^BOOL(NSString *route, NSDictionary<NSString *, id> *parameters) {
NEConversationOpenIntent *intent = makeIntent(route, parameters);
return [weakShell openConversation:intent];
} forNavigationController:chatNavigation];
步骤四:子页面呈现
通讯录、我的等根导航在执行原 push 前调用公开入口:
objective-cif (![shell presentSectionChild:child
fromNavigationController:sectionNavigation
animated:YES]) {
[sectionNavigation pushViewController:child animated:YES];
}
返回值含义:
| 返回值 | 含义 | 调用方处理 |
|---|---|---|
| YES | 页面已在右侧详情栏呈现 | 不再 push |
| NO | Compact 或旧布局 | 继续原导航 |
详情中的更深层页面沿用自己的导航栈。
步骤五:侧栏刷新与自绘标题栏
| 场景 | 处理方式 |
|---|---|
| 自定义导航栏文案或启用态变化 | 调用 [shell refreshRailNavigation] 刷新侧栏 |
| 分区角标变化 | 调用 [shell updateRailItems] |
| 侧栏返回入口识别 | 按类名识别 NEUnifiedBackButton |
| 收起入口识别 | 按 id.arrowDown/id.adaptiveBack 识别 |
| 右侧操作识别 | 按 id.sureButton/id.multiSelect/id.adaptiveAction/id.createTopic/id.threePoint 识别 |
| 列内 present 页面出现或消失 | 监听 NEAdaptivePresentationDidChange,据此重解析侧栏 |
| 列内底部弹窗展示/关闭 | 监听 NEAdaptiveOverlayDidPresent(userInfo 携带 dismiss block)和 NEAdaptiveOverlayDidDismiss;侧栏返回键会先调用 dismiss 关闭弹层 |
| 无标题栏的 push 页面 | 导航栈深大于 1 时,侧栏自动补返回入口并执行 pop |
布局与侧栏规则
各模式布局:
| 模式 | 布局表现 |
|---|---|
| Compact | 单页呈现,聊天输入区贴底;从聊天返回列表后右列回到空占位,再次打开会重新创建会话页面 |
| Medium/Expanded | 左列列表 + 右列详情;通讯录与 我的 从首次显示起就保持左侧根页面与右侧空详情,无需先点开子页面;返回根页面时清空右侧详情,双栏仍保留 |
navigation rail 规则:
- 位于窗口右侧(
railUsesTrailingEdge = YES)。 - 返回入口在顶部,页面右侧操作在其下方,消息/通讯录/我的入口组固定在侧栏底部。
- 返回与右侧操作统一为圆形控件(浅色底 + 细描边);页面右侧按钮文案中的计数(如「确定(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 时跟随 selectedTintColor)与文字颜色 |
railBackgroundColor/dividerColor/selectedTintColor/normalTintColor |
UIColor | 侧栏背景、分栏分隔线、选中与未选中态颜色 |
usesSystemBackButtonStyle/backImage/backTintColor/backAccessibilityLabel |
BOOL/UIImage/UIColor/NSString | 返回按钮样式;关闭系统样式时使用皮肤返回图 |
mediumThreshold/expandedThreshold/compactAspectRatio |
CGFloat | 中/宽窗口判定阈值与紧凑比例 |
singleContentMinimumWidth/masterMinimumWidth/detailMinimumWidth/masterMaximumWidth |
CGFloat | 单列、主列、详情列的最小与最大宽度 |
mediumMasterWidth/expandedMasterWidth/dividerWidth |
CGFloat | 中/宽窗口主列宽度与分栏宽度 |
contentTopInset/contentBackgroundColor |
CGFloat/UIColor | 内容区顶部留白与背景色 |
railItemsTopInset 已废弃:分区入口组固定在侧栏底部,不再读取顶部内边距。
关键类型
| 类型 | 说明 |
|---|---|
NEAdaptiveShellViewController |
外壳控制器。initWithSections:detailNavigationController:configuration:;presentSectionChild:fromNavigationController:animated:、openConversation:、selectSection:、showConversationList、refreshRailNavigation、updateRailItems、detachSectionsForLegacyTransfer;回调 onSectionSelected、onConversationOpened、onCompactChatVisibilityChanged、onLegacyFallback、onContentLayout、onDetailPlaceholderChanged |
NEAdaptiveShellConfiguration |
列宽、阈值、侧栏与控件样式配置 |
NEChatDetailHostController |
右侧详情栏容器,稳定持有聊天导航栈 |
NEConversationNavigationCoordinator |
详情栏会话导航:controllerFactory、presentationAction、open:、showPlaceholder:、reset |
NEConversationOpenIntent |
打开会话的意图:key、route、parameters、requiresPresentationAction |
NEAdaptiveWindowContext/NEWindowSnapshot |
窗口尺寸与安全区采样;快照包含 displayScale 与 reservedRegions(激活的 division/occlusion 占位区) |
NEAdaptiveLayoutPolicy |
无状态布局策略,resolveWithWindow:configuration: 返回 NEAdaptiveLayoutDecision(mode 为 compact/medium/expanded,并给出各列宽度) |
NEAdaptiveDeviceGate |
设备门禁:isFoldableDevice、adaptiveHostActive、foldableBySceneGeometry;位于 NEBaseUIKitOC |
NEAdaptiveBottomSheetController |
列内底部弹层基类,位于 NEBaseUIKitOC |
注意事项
- 普通 iPhone、iPad 与普通模拟器必须继续使用原有 Tab 与 push 结构,不要启用外壳。
- 外壳不接管 SDK、会话订阅与 ViewModel;未读订阅仍由宿主或原组件负责。
- 自定义路由应使用自己的
controllerFactory,不要在列表的onOpenConversation前置 hook 中无条件调用标准 factory。 - 视图层级与栏宽属于外壳职责,页面内部不要再次根据机型计算宽度。
- 折叠态返回列表时不要重置列表
contentOffset;外壳已按当前会话恢复滚动位置。
此文档是否对你有帮助?




