一、核心背景:折叠屏适配的本质变化

折叠屏(如 iPhone Duo)带来了外屏/内屏切换、半折悬停、铰链分割等全新形态。适配的本质不再是"按机型写布局",而是按连续窗口空间写规则。Kuikly 将窗口状态、安全区、铰链等系统差异封装为跨端共享状态,大幅降低业务成本。

版本与平台支持矩阵(重要):

能力

KuiklyUI 版本

平台

生效条件

hingeStatus

2.29.0+

iOS

iOS 27.1+ 折叠设备(如 iPhone Duo),Native 通过 UIHingeInteraction 写入,随 rootViewSizeDidChanged 更新

hingeStatus

2.31.0+

HarmonyOS

API 12+ 可折叠设备,通过 display.getFoldStatus / display.on('foldStatusChange') 映射为 HingeStatus

reservedRegions

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 在折叠屏等新形态下的一码多端适配能力。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐