iOS

折叠屏适配

更新时间: 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;外壳已按当前会话恢复滚动位置。
此文档是否对你有帮助?
有帮助
去反馈
  • 概述
  • 组件依赖
  • 接入步骤
  • 步骤一:启动门禁
  • 步骤二:创建外壳
  • 步骤三:会话呈现
  • 步骤四:子页面呈现
  • 步骤五:侧栏刷新与自绘标题栏
  • 布局与侧栏规则
  • 配置项
  • 关键类型
  • 注意事项