Kuikly 跨端框架折叠屏(iPhone Duo)适配指南
一、核心背景:折叠屏适配的本质变化
折叠屏(如 iPhone Duo)带来了外屏/内屏切换、半折悬停、铰链分割等全新形态。适配的本质不再是"按机型写布局",而是按连续窗口空间写规则。Kuikly 将窗口状态、安全区、铰链等系统差异封装为跨端共享状态,大幅降低业务成本。
版本与平台支持矩阵(重要):
|
能力 |
KuiklyUI 版本 |
平台 |
生效条件 |
|
|
2.29.0+ |
iOS |
iOS 27.1+ 折叠设备(如 iPhone Duo),Native 通过 |
|
|
2.31.0+ |
HarmonyOS |
API 12+ 可折叠设备,通过 |
|
|
2.29.0+ |
仅 iOS |
仅 iOS 27.1+ 折叠设备返回数据;HarmonyOS 及其他平台恒为空列表 |
条件不满足时(普通手机、平板、不可折叠设备、更低系统版本),
hingeStatus为UNKNOWN(0),业务可直接按未知处理。
二、Kuikly 给业务暴露了什么
PagerData / LocalConfiguration 中直接提供:
kotlin
pageData.pageViewWidth / pageViewHeight // 当前可用宽高
pageData.safeAreaInsets // 上右下左安全距离
pageData.reservedRegions // 折缝 + 遮挡区列表(仅 iOS 27.1+ 折叠设备,其他平台为空列表)
hingeStatus // UNKNOWN(0)=未知 / 合上(1) / PARTIALLY_OPEN(2)=半开 / 全开(3)
数据随 rootViewSizeDidChanged 自动推送,业务无需自行监听 UIScene。
⚠️ iOS 多 Window 场景例外:悬浮窗、分屏等场景下,需在 iOS 宿主实现
viewControllerHostWindow方法,指定当前页面获取safeAreaInsets的参考窗口,否则可能拿到错误的安全区。
三、适配四步法
1. 布局别写死,跟着可用宽高走
使用 flex(1f)、百分比宽度与最大宽度限制,展开态可增加列数或左右分栏。
kotlin
// Kuikly DSL
View {
attr {
flex(1f)
width(ctx.pageData.pageViewWidth * 0.8f)
maxWidth(600f)
}
}
// Kuikly Compose DSL
val pageWidth = LocalConfiguration.current.pageViewWidth
Box(Modifier.width(minOf(pageWidth * 0.8f, 600f).dp)) { /* ... */ }
2. 安全区随形态动态避让
safeAreaInsets 需在订阅中更新,不可仅在 init 只读一次——折叠瞬间安全区会变化。
- Kuikly DSL:在
attr中引用pageData.safeAreaInsets,尺寸变化后布局属性会自动重算;
- Compose DSL:必须通过
LocalConfiguration.current订阅,才能触发重组更新。
kotlin
// Kuikly DSL
View {
attr {
flex(1f)
paddingTop(ctx.pageData.safeAreaInsets.top)
paddingLeft(ctx.pageData.safeAreaInsets.left)
paddingBottom(ctx.pageData.safeAreaInsets.bottom)
paddingRight(ctx.pageData.safeAreaInsets.right)
}
// 需要安全区保护的前景内容
}
// Kuikly Compose DSL(LocalConfiguration.current 即订阅)
val configuration = LocalConfiguration.current
val safe = configuration.pageData.safeAreaInsets
Box(Modifier.fillMaxSize().background(bgColor)) { // 背景铺满
Column(
Modifier.fillMaxSize().absolutePadding(
left = safe.left.dp, top = safe.top.dp,
right = safe.right.dp, bottom = safe.bottom.dp,
)
) {
// 需要安全区保护的前景内容
}
}
iPhone Duo 的导航栏、工具栏可能移到屏幕侧边,因此 left / right 也要处理,不能只留上下边距。
3. 折缝和遮挡区做局部避让
通过 reservedRegions 获取铰链/挖孔位置,背景可延伸,但前景内容(按钮、文字)必须避让。
区域字段:kind(OCCLUSION=遮挡区 / DIVISION=折缝区)、active(当前是否生效,如设备平铺时折缝未生效)、x, y, width, height(坐标相对页面根视图,单位为点)、marginTop/Left/Bottom/Right(frame 中为交互内容预留的边距)。
kotlin
// 避让所有生效的遮挡区域
pageData.reservedRegions.forEach { region ->
if (region.active && region.kind == ReservedRegionKind.OCCLUSION) {
val bottom = region.y + region.height
// 按需让开该区域
}
}
// 判断设备是否处于半折叠(内容分居折缝两侧)
val halfFolded = pageData.hingeStatus == HingeStatus.PARTIALLY_OPEN
4. 导航与返回栈要"懂形态"
小屏整页 push,大屏左列表右详情;手势优先级:先消内部层级 → 再消详情区 → 最后整页返回。
Kuikly 在共享层建立了统一的导航语义:业务代码只表达"前进 / 返回 / 选中",框架根据当前窗口形态映射为整页跳转(小屏)或 pane 内内容替换(大屏)。大屏返回手势优先弹出当前 pane 内部栈,pane 栈为空时才由外层页面处理。
iPhone Duo 侧置系统栏场景下,可通过 UINavigationBar / UIToolbar(Kuikly DSL)接入宿主原生系统栏,由系统根据姿态处理栏的位置与排列,业务侧只配置标题、按钮与点击事件。
四、业务案例实战
Kuikly 已在多款腾讯头部产品中完成 iPhone Duo 新形态适配实践:腾讯自选股解决了侧边栏、安全距离、摄像头与折叠带等保留区域的规避问题;腾讯新闻电台播放页则实现了封面、话题条与播放控件随屏幕宽度自适应,展开态信息更丰富、窄屏聚焦播放体验。两者共同验证了 Kuikly 在折叠屏等新形态下的一码多端适配能力。


更多推荐
所有评论(0)