折叠屏展开后别只做“拉宽“：从断点到双栏布局的响应式适配实践【鸿蒙心迹】

菜鸟不学编程

71人浏览 · 2026-09-24 16:55:21

菜鸟不学编程 · 2026-09-24 16:55:21 发布

👋 你好，欢迎来到我的博客！我是【菜鸟学鸿蒙】
我是一名在路上的移动端开发者，正从传统“小码农”转向鸿蒙原生开发的进阶之旅。为了把学习过的知识沉淀下来，也为了和更多同路人互相启发，我决定把探索 HarmonyOS 的过程都记录在这里。

🛠️ 主要方向：ArkTS 语言基础、HarmonyOS 原生应用（Stage 模型、UIAbility/ServiceAbility）、分布式能力与软总线、元服务/卡片、应用签名与上架、性能与内存优化、项目实战，以及 Android → 鸿蒙的迁移踩坑与复盘。
🧭 内容节奏：从基础到实战——小示例拆解框架认知、专项优化手记、实战项目拆包、面试题思考与复盘，让每篇都有可落地的代码与方法论。
💡 我相信：写作是把知识内化的过程，分享是让生态更繁荣的方式。

如果你也想拥抱鸿蒙、热爱成长，欢迎关注我，一起交流进步！🚀

前言

很多开发者第一次在折叠屏模拟器里打开自己的 App，展开之后的反应是：“能用，但看起来很奇怪。”

内容被拉伸成宽条，中间一片空白，或者列表项铺得太宽根本没法看。这不是折叠屏的问题，是布局本身没有为宽屏空间做过设计。

手机单栏页面在折叠屏展开态下面临的核心挑战，并不是"怎么判断折叠屏"，而是：当可用窗口宽度从 360vp 左右跳到 700vp 以上，布局信息层级应该怎么重新组织。

这篇文章以一个典型的"列表页→详情页"场景为例，整理从断点感知、布局切换到状态保持的完整适配思路。

一、把问题说清楚：不是折叠屏检测，是窗口宽度响应

先纠正一个常见思路偏差。

很多开发者遇到折叠屏适配需求，第一反应是去查"怎么判断当前设备是不是折叠屏"。这个思路容易把问题复杂化。

HarmonyOS 官方推荐的适配思路是：不依赖设备类型判断，而是监听窗口可用宽度（breakpoint），根据宽度范围决定布局形式。

这个思路的好处是天然兼容多种情况：

折叠屏展开态；
折叠屏分屏态（窗口被压缩，宽度反而变小）；
平板设备；
多窗口模式下被缩窄的手机应用；
竖屏/横屏切换。

所有这些情况都会反映为窗口宽度的变化，统一用断点处理比逐设备判断更稳定。

二、官方断点体系

HarmonyOS 官方文档定义了一套基于窗口宽度的断点系统。根据官方资料，常用的参考断点范围如下：

断点名称	窗口宽度范围	典型场景
xs	[0, 320vp)	超小屏
sm	[320vp, 600vp)	普通手机竖屏
md	[600vp, 840vp)	折叠屏展开、小型平板
lg	[840vp, +∞)	大平板、2in1 设备

对于"列表页在折叠屏展开后变双栏"这个场景，关键就是 sm → md 这个跳变。

ArkUI 的 GridRow 组件原生支持断点，开发者可以直接在 GridCol 的 span 属性中为不同断点配置不同的列宽，不需要手动监听窗口尺寸。

三、最小场景定义

这次用一个最小示例验证以下目标：

手机态（sm 断点）：列表页全屏单栏展示，点击跳转详情页；
宽屏态（md/lg 断点）：左侧固定列表，右侧展示选中项详情，双栏并排。
折叠↔展开过程中，当前选中项保持不变。

布局切换点：窗口宽度 ≥ 600vp。

四、核心代码实现

4.1 用 `GridRow` + `GridCol` 控制双栏切换

GridRow 是 ArkUI 提供的响应式栅格容器，内置断点监听能力。GridCol 的 span 属性接受 GridColColumnOption 对象，可以为每个断点分别配置占用列数。

下面这段代码实现了：sm 断点时列表和详情各自全宽（通过条件渲染只显示一个），md/lg 断点时左 4 列列表 + 右 8 列详情并排。

// MainPage.ets
import { GridRow, GridCol, GridColColumnOption } from '@ohos.arkui.advanced.Grid'

@Entry
@Component
struct MainPage {
  // 当前选中的列表项索引，-1 表示未选中
  @State selectedIndex: number = -1
  // 当前断点标识
  @State currentBreakpoint: string = 'sm'

  private items: string[] = [
    '消息通知设置', '账号与安全', '隐私管理', '通用设置', '关于本应用'
  ]

  build() {
    GridRow({
      breakpoints: {
        value: ['600vp', '840vp'],
        reference: BreakpointsReference.WindowSize
      },
      columns: { sm: 4, md: 12, lg: 12 },
      gutter: { x: 16 }
    }) {
      // 左侧列表区
      // sm 断点：如果有选中项则隐藏列表（跳转逻辑）
      // md/lg 断点：始终显示
      GridCol({
        span: { sm: 4, md: 4, lg: 3 }
      }) {
        if (this.currentBreakpoint === 'sm' && this.selectedIndex !== -1) {
          // 手机态已选中时，列表区不参与渲染
          // 实际项目中这里通常是路由跳转，此处用条件渲染演示断点切换逻辑
        } else {
          this.buildListArea()
        }
      }

      // 右侧详情区：sm 断点仅在选中时全屏展示，md/lg 始终占位
      GridCol({
        span: { sm: 4, md: 8, lg: 9 }
      }) {
        if (this.currentBreakpoint !== 'sm' || this.selectedIndex !== -1) {
          this.buildDetailArea()
        } else {
          this.buildPlaceholder()
        }
      }
    }
    .onBreakpointChange((breakpoint: string) => {
      // GridRow 断点变化回调，更新当前断点状态
      this.currentBreakpoint = breakpoint
    })
    .width('100%')
    .height('100%')
  }

  @Builder
  buildListArea() {
    List({ space: 8 }) {
      ForEach(this.items, (item: string, index: number) => {
        ListItem() {
          Row() {
            Text(item)
              .fontSize(16)
              .fontColor('#182431')
              .layoutWeight(1)
            Image($r('app.media.ic_arrow_right'))
              .width(20)
              .height(20)
          }
          .width('100%')
          .padding({ left: 16, right: 16, top: 12, bottom: 12 })
          .backgroundColor(this.selectedIndex === index ? '#E6F0FF' : Color.White)
          .borderRadius(8)
          .onClick(() => {
            this.selectedIndex = index
          })
        }
      })
    }
    .width('100%')
    .padding({ top: 8 })
  }

  @Builder
  buildDetailArea() {
    if (this.selectedIndex === -1) {
      this.buildPlaceholder()
    } else {
      Column() {
        Text(this.items[this.selectedIndex])
          .fontSize(20)
          .fontWeight(FontWeight.Medium)
          .margin({ bottom: 12 })
        Text('这里是详情内容区域，对应：' + this.items[this.selectedIndex])
          .fontSize(14)
          .fontColor('#66182431')
      }
      .width('100%')
      .padding(24)
      .backgroundColor(Color.White)
      .borderRadius(12)
    }
  }

  @Builder
  buildPlaceholder() {
    Column() {
      Text('请从左侧选择一项')
        .fontSize(14)
        .fontColor('#99182431')
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
  }
}

4.2 几个地方值得单独看一下

BreakpointsReference.WindowSize

GridRow 的 breakpoints.reference 有两个选项：WindowSize（基于窗口宽度）和 ComponentSize（基于组件自身宽度）。折叠屏适配场景应该用 WindowSize，因为我们关心的是整个可用区域的宽度，而不是某个容器的宽度。

onBreakpointChange 回调

GridRow 提供了 onBreakpointChange(callback: (breakpointName: string) => void) 回调，在断点发生变化时触发，回调参数是字符串形式的断点名称（如 'sm'、'md'、'lg'）。把这个值存进 @State 变量，就可以在其他地方（比如决定是否做路由导航）拿到当前断点。

列数要配齐

GridRow 的 columns 如果只配了部分断点（比如只写了 md: 12），其他断点会使用默认值。建议把用到的断点都显式写明，避免未预期的默认值行为。

五、展开→折叠→再展开时的状态保持

折叠屏适配里另一个值得关注的问题：用户展开后选中了某一项，折叠手机，再展开，选中状态是否还在？

只要 selectedIndex 是 @State 修饰的变量，且页面组件没有被销毁重建，状态就会保持。

但需要注意：在 sm 断点下，"手机态"通常用路由跳转（Router 或 Navigation）实现列表→详情的切换，而不是像双栏那样在一个页面里用条件渲染控制。这意味着从折叠态（已进入详情路由）切换到展开态时，还需要处理一个问题：当前路由栈里已经是详情页了，但宽屏下期望呈现双栏，详情内容要回到主页的右侧列。

官方推荐的做法是使用 Navigation 组件，它内置了 navBarWidth、mode 属性和自适应能力，可以根据窗口宽度自动在单栏（NavigationMode.Stack）和双栏（NavigationMode.Split）之间切换，且路由栈状态保持连续。

// 使用 Navigation 组件实现模式自动切换
Navigation() {
  // NavBar 内容：列表区
  this.buildListArea()
}
.navBarWidth('40%')           // 宽屏时左侧导航栏宽度
.navBarWidthRange(['240vp', '50%'])  // 允许的宽度范围
.mode(NavigationMode.Auto)    // Auto 模式：由系统根据窗口宽度自动切换 Stack/Split
.hideNavBar(false)

NavigationMode.Auto 是关键。在这个模式下，系统会自动判断当前窗口宽度，决定用单栏 Stack 还是双栏 Split。开发者不需要手动监听断点来切换模式，路由栈也由 Navigation 统一管理。

六、固定 vp、百分比宽度和弹性布局的使用边界

这部分容易出现一个理解偏差。

固定 vp

适合写死最小/最大尺寸约束（minWidth、maxWidth），或者组件本身的 padding、间距、图标尺寸。不适合用在容器宽度上，一旦写了固定宽度，宽屏下就会出现空白或溢出。

百分比宽度

width('100%') 对容器来说基本是正确的起手姿势，但在 GridCol 内部，子组件的百分比宽度是相对于 GridCol 宽度计算的，而 GridCol 的宽度本身是由栅格系统按断点分配的。所以 GridCol 子组件写 width('100%') 是合理的。

弹性布局（layoutWeight / Flex）

layoutWeight 和 Flex 布局的弹性分配在同一行内的子元素上非常有效，但不要用来替代栅格系统承担跨断点的布局角色。两者定位不同：栅格负责大块区域的断点切换，弹性布局负责一行内子元素的空间分配。

七、容易出问题的地方

断点值单位必须带 vp

breakpoints.value 数组里的字符串必须包含单位，写成 '600vp' 而不是 600 或 '600'。如果漏掉单位，断点不会按预期触发。

sm 断点双栏隐藏逻辑不要依赖 visibility

用 Visibility.Hidden 隐藏组件只是在视觉上不显示，组件仍然参与布局计算，会占据宽度。需要完全移除布局占位时，应该用 Visibility.None 或条件渲染（if）。

NavigationMode.Auto 的宽度阈值

NavigationMode.Auto 下系统从 Stack 切换到 Split 的宽度阈值，官方文档说明是以组件宽度为基准，通常 ≥600vp 时切换为 Split。如果 Navigation 没有撑满全屏（比如外层有 padding），可能达不到切换阈值，需要留意。

折叠态分屏时窗口宽度可能更小

折叠屏折叠后进入分屏，单侧窗口宽度可能比普通手机更小（甚至进入 xs 断点范围）。布局系统要为 xs 也提供合理的回退，而不是只考虑 sm 和 md。

八、多形态页面验证清单

在提交测试或发布之前，可以对照以下清单逐项检查：

sm 断点（<600vp）：列表页单栏正常，内容不溢出，可正常点击跳转；
md 断点（600vp～840vp）：双栏布局正确显示，左右比例合理，列表选中状态可见；
lg 断点（>840vp）：双栏比例与 md 有所区别（左侧可适当收窄），右侧内容区更宽；
展开→折叠：从双栏态折叠后，正确切换为单栏态，不出现布局残留或白屏；
折叠→展开：从单栏态展开后，双栏恢复，已选中项仍然高亮；
分屏模式：应用被压窄后，布局按断点正确回退；
横屏/竖屏切换：特别是平板和折叠屏展开态的横屏，确认断点是否触发正确；
空状态：宽屏下未选中任何列表项时，右侧占位内容明确，不是空白；
无固定宽度容器：全局检查有没有写死宽度导致宽屏溢出或留白的容器。

开发经验总结

断点优先，设备类型其次。 窗口宽度是布局决策的第一依据，在此基础上才考虑设备类型的特殊处理。
GridRow + onBreakpointChange 是响应式布局的基础搭配。 GridCol 的 span 配置可以覆盖绝大多数双栏切换场景，不需要额外的监听代码。
Navigation 的 Auto 模式适合列表-详情场景。 它处理了路由栈连续性问题，避免手动管理 Stack/Split 切换带来的状态丢失。
宽屏适配不等于等比放大。 md 断点下更合理的做法是重新设计信息层级（双栏并排），而不是把单栏内容拉宽。
验证要盖折叠↔展开的过渡态，而不只是静态展开态。 状态切换过程中的布局行为往往是最容易出问题的地方。