HarmonyOS 折叠屏与鸿蒙电脑适配：布局一崩，八成是断点没定义

引子：折叠一开，界面就散了

V哥第一次把应用装到折叠屏上，没改任何一行布局代码，展开的那一下，界面直接"炸"了：卡片挤成一团，侧边栏浮在内容上面遮了一半，底部 Tab 被顶出了屏幕。

第一反应是代码写得不对。后来照着 MultiWeather 把断点接上，问题就没了。这事儿让V哥记住一句铁律——

折叠态切换出问题，八成是断点没定义，不是代码写错。

下面把这条判断拆开讲，顺便把官方给的几把"钥匙"（窗口尺寸回调、SideBarContainerType、GridRow/GridCol、Navigation 模式、PC/2in1 键鼠）一条条过一遍。

一、为什么折叠态/展开态切换最容易出事

折叠屏最特殊的不是"两块屏"，是窗口宽度在瞬间跳变一个量级。折叠态近似一台直板机（SM 断点），展开态往往直接跨进 MD 甚至 LG。如果你的布局只按"当前这一屏"写死，那跳变瞬间没有第二套规则兜底，散架是必然。

官方其实把这件事说得很直白：

不推荐使用折叠状态监听接口实现页面布局的响应式布局和接续，避免在窗口变化但折叠状态未改变的场景下布局未能及时调整，出现页面异常。（多设备适配屏幕差异）

这句话点破一个常见误区：很多人第一反应是去监听 display.on('foldStatusChange')（折叠状态变化）。但折叠状态和窗口尺寸不是一一对应的——窗口可以缩放、分屏、旋转，而折叠状态没变。真正驱动布局的应该是窗口尺寸，也就是断点。 折叠状态监听留给悬停态、相机预览这类功能适配用，别拿它做布局主逻辑。

所以V哥的判断是：先问"V哥有没有断点"，再问"V哥代码写错了没"。 九成的"一折就崩"，卡在前者。

二、断点不是玄学：WidthBreakpoint + 窗口尺寸回调怎么落

HarmonyOS 横向断点按窗口宽度（vp）划分，官方推荐区间：

拿到断点有两种姿势，且要配合用：主动获取 + 被动监听。

• 主动获取：UIContext.getWindowWidthBreakpoint() 返回当前 WidthBreakpoint 枚举值，在 Ability/页面初始化时调一次校准。
• 被动监听：window.on('windowSizeChange') 在窗口尺寸变化时回调，在回调里重新取断点。官方对双折叠开合的原话是：

双折叠开合状态变化时会伴随着窗口尺寸的变化，可通过注册 on('windowSizeChange') 事件监听器来捕获窗口尺寸变化，在回调函数中重新计算当前断点，通过断点变化更新 UI 布局。（多设备适配屏幕差异）

下面是V哥自写的断点监听封装，把"取断点"和"监听回调"收口到一处，业务页面只认 state.widthBp：

<span>// BreakpointUtil.ets —— V哥自己的断点监听封装</span>
<span>import</span> { <span>window</span> } <span>from</span> <span>'@kit.ArkUI'</span>;
<span>import</span> { <span>UIContext</span> } <span>from</span> <span>'@kit.ArkUI'</span>;

<span>// 把官方推荐的横向断点阈值记成常量，避免散落在业务里到处写魔法数字</span>
<span>export</span> <span>const</span> <span>BP</span> = {
  <span>XS_MAX</span>: <span>320</span>,
  <span>SM_MAX</span>: <span>600</span>,
  <span>MD_MAX</span>: <span>840</span>,
  <span>LG_MAX</span>: <span>1440</span>
} <span>as</span> <span>const</span>;

<span>@Observed</span>
<span>export</span> <span>class</span> <span>WindowState</span> {
  <span>// 当前横向断点，UI 只订阅它</span>
  <span>public</span> <span>widthBp</span>: <span>WidthBreakpoint</span> = <span>WidthBreakpoint</span>.<span>WIDTH_SM</span>;
}

<span>export</span> <span>class</span> <span>BreakpointUtil</span> {
  <span>private</span> <span>uiContext</span>: <span>UIContext</span> | <span>null</span> = <span>null</span>;
  <span>public</span> <span>state</span>: <span>WindowState</span> = <span>new</span> <span>WindowState</span>();

  <span>// 在拿到 UIContext 后调一次：主动校准</span>
  <span>init</span>(<span>uiContext</span>: <span>UIContext</span>): <span>void</span> {
    <span>this</span>.<span>uiContext</span> = uiContext;
    <span>this</span>.<span>refresh</span>();
  }

  <span>// 取当前断点：官方 UIContext 提供的入口</span>
  <span>refresh</span>(): <span>void</span> {
    <span>if</span> (<span>this</span>.<span>uiContext</span> === <span>null</span>) {
      <span>return</span>;
    }
    <span>this</span>.<span>state</span>.<span>widthBp</span> = <span>this</span>.<span>uiContext</span>.<span>getWindowWidthBreakpoint</span>();
  }

  <span>// 窗口尺寸变化回调：把"重新取断点"收口到这一处</span>
  <span>onSizeChange</span>: <span>(<span>size: <span>window</span>.Size</span>) =></span> <span>void</span> = <span>(<span>_size: <span>window</span>.Size</span>) =></span> {
    <span>this</span>.<span>refresh</span>();
  };
}

记住一个V哥的小判断：回调里只做"刷新断点"，别在回调里堆业务布局逻辑。 让 ArkUI 的声明式绑定去重算 UI，你只负责喂准断点这一个状态。

三、SideBarContainerType 怎么选：Embed / Overlay / AUTO / DISPLACE

侧边栏是最常见的"一多"分水岭——窄屏要收起、宽屏要常驻。SideBarContainer 的构造参数 type 决定侧边栏"怎么摆"，枚举V哥整理成一张带判断的表：

官方对前两个的定义是：

Embed：侧边栏嵌入到组件内，和内容区并列显示。Overlay：侧边栏浮在内容区上面，不会影响内容区的大小。（SideBarContainer）

V哥的口诀是：窄屏用 Overlay（浮起来不占地），宽屏用 Embed（并排常驻更顺手）。 MultiWeather 的写法就是拿 WidthBreakpoint.WIDTH_SM 当分界：是 SM 就 Overlay，否则 Embed。你也可以直接用 AUTO，把 minSideBarWidth / minContentWidth 配好，让系统替你切。

下面这段是接在第二节 BreakpointUtil 上的页面骨架（V哥自写的命名与注释，不抄官方）：

<span>// DashboardPage.ets —— 一份代码吃下折叠屏与鸿蒙电脑</span>
<span>import</span> { <span>BreakpointUtil</span> } <span>from</span> <span>'../utils/BreakpointUtil'</span>;
<span>import</span> { <span>window</span> } <span>from</span> <span>'@kit.ArkUI'</span>;

<span>@Entry</span>
<span>@Component</span>
struct <span>DashboardPage</span> {
  <span>private</span> <span>bpUtil</span>: <span>BreakpointUtil</span> = <span>new</span> <span>BreakpointUtil</span>();
  <span>@State</span> <span>isSideBarOpen</span>: <span>boolean</span> = <span>true</span>;

  <span>aboutToAppear</span>(): <span>void</span> {
    <span>this</span>.<span>bpUtil</span>.<span>init</span>(<span>this</span>.<span>getUIContext</span>());
    <span>// 关键：注册窗口尺寸变化监听，断点跟着窗口走</span>
    <span>window</span>.<span>getLastWindow</span>().<span>then</span>(<span>(<span>win: <span>window</span>.Window</span>) =></span> {
      win.<span>on</span>(<span>'windowSizeChange'</span>, <span>this</span>.<span>bpUtil</span>.<span>onSizeChange</span>);
    }).<span>catch</span>(<span>() =></span> {});
  }

  <span>aboutToDisappear</span>(): <span>void</span> {
    <span>// 注销监听，别留内存尾巴</span>
    <span>window</span>.<span>getLastWindow</span>().<span>then</span>(<span>(<span>win: <span>window</span>.Window</span>) =></span> {
      win.<span>off</span>(<span>'windowSizeChange'</span>, <span>this</span>.<span>bpUtil</span>.<span>onSizeChange</span>);
    }).<span>catch</span>(<span>() =></span> {});
  }

  <span>build</span>(<span></span>) {
    <span>// 窄屏 SM 用悬浮，更宽用嵌入</span>
    <span>SideBarContainer</span>(
      <span>this</span>.<span>bpUtil</span>.<span>state</span>.<span>widthBp</span> === <span>WidthBreakpoint</span>.<span>WIDTH_SM</span>
        ? <span>SideBarContainerType</span>.<span>Overlay</span>
        : <span>SideBarContainerType</span>.<span>Embed</span>
    ) {
      <span>// 第一个子组件：侧边栏</span>
      <span>Column</span>() { <span>/* 导航 / 城市管理列表 */</span> }.<span>width</span>(<span>'100%'</span>)
      <span>// 第二个子组件：内容区（栅格多列见下一节）</span>
      <span>this</span>.<span>contentArea</span>()
    }
    .<span>sideBarWidth</span>(<span>280</span>)
    .<span>minSideBarWidth</span>(<span>200</span>)
    .<span>minContentWidth</span>(<span>360</span>)
    .<span>showSideBar</span>(<span>this</span>.<span>isSideBarOpen</span>)
  }

  <span>@Builder</span>
  <span>contentArea</span>(<span></span>) {
    <span>// 占位：真实内容见 GridRow/GridCol 示例</span>
    <span>Column</span>() {}
  }
}

四、GridRow/GridCol 栅格多列：把"信息密度"交给断点

侧边栏解决"导航在哪"，栅格解决"内容铺几列"。GridRow 是容器、GridCol 是子项，两者用 columns 和 span 按断点分别配置，系统自动落列数——这就是"响应式"而不是"自适应"：跨断点直接换结构，不是小幅伸缩。

<span>GridRow</span>({
  <span>// 不同断点不同列数：窄屏 1 列，平板 2 列，大屏 3 列，电脑 4 列</span>
  <span>columns</span>: { <span>sm</span>: <span>1</span>, <span>md</span>: <span>2</span>, <span>lg</span>: <span>3</span>, <span>xl</span>: <span>4</span> },
  <span>breakpoints</span>: { <span>value</span>: [<span>'320vp'</span>, <span>'600vp'</span>, <span>'840vp'</span>, <span>'1440vp'</span>] }
}) {
  <span>ForEach</span>(<span>this</span>.<span>cards</span>, <span>(<span>item: Card</span>) =></span> {
    <span>GridCol</span>({ <span>span</span>: <span>1</span> }) {
      <span>// 一张卡片：图文组合，跨断点只是"挤几列"变，结构不变</span>
      <span>this</span>.<span>cardItem</span>(item)
    }
  }, <span>(<span>item: Card</span>) =></span> item.<span>id</span>)
}
.<span>onBreakpointChange</span>(<span>(<span>bp: <span>string</span></span>) =></span> {
  <span>// 这里只做日志/埋点，列数已由 columns 自动接管</span>
  <span>console</span>.<span>info</span>(<span>'current breakpoint: '</span> + bp);
})

V哥的判断：栅格的 span 别写死，按断点给阶梯。 窄屏让一张卡片占满整行（span 取满列数），宽屏让它只占一格，信息密度自然就上去了。真机表现请以真机实测为准——不同设备密度下观感会有出入。

五、Navigation 单双栏：Auto 模式与 600vp 那条隐线

列表进详情这类"导航 + 内容"结构，Navigation 比手写分栏省心。它有个 mode：

官方对 Auto 的断点计算：

NavigationMode.Auto：基于组件宽度自适应单栏和双栏。Auto 模式断点计算：默认 600vp（minNavBarWidth 240vp + minContentWidth 360vp）。（Navigation）

也就是说，Navigation 宽度 < 600vp 自动单栏，≥ 600vp 自动双栏。想改这条线，调 navBarWidth 或 minContentWidth 即可，不用自己写 if/else。接法很简单：

<span>Navigation</span>() {
  <span>// NavDestination 列表与详情</span>
}
.<span>mode</span>(<span>NavigationMode</span>.<span>Auto</span>)   <span>// 默认即此值，可省略</span>
.<span>navBarWidth</span>(<span>280</span>)            <span>// 影响断点计算中的 minNavBarWidth</span>
.<span>minContentWidth</span>(<span>360</span>)

V哥的口诀：能 Auto 就别手写双栏切换，那条 600vp 隐线是系统帮你踩好的，自己重写反而容易在边界宽度上抖一下。

六、PC/2in1：鼠标悬停与拖拽，别把触屏界面直接搬过来

到了鸿蒙电脑 / 2in1，窗口是自由窗——用户能拖大拖小、能并排多窗。这时候除了断点，还要补两件事：

第一，悬停态（hover）。 触屏只有"按下"，鼠标有"划过"这个中间态。PC 上划过列表项、按钮没有反馈，用户会觉得"死的"。官方对 PC/2in1 设备的特性明确写着：

PC/2in1 设备支持全屏或自由窗口显示应用，支持键鼠。（一次开发多端部署概览）

落到代码就是 onHover 事件 + hoverEffect 属性：

<span>Button</span>(<span>'打开'</span>)
  .<span>onHover</span>(<span>(<span>isHover: <span>boolean</span></span>) =></span> {
    <span>// 鼠标划过变亮，离开复原</span>
    <span>this</span>.<span>hoverBg</span> = isHover ? <span>'#EAF3FF'</span> : <span>'#FFFFFF'</span>;
  })
  .<span>hoverEffect</span>(<span>HoverEffect</span>.<span>Scale</span>)   <span>// 悬浮轻微放大，桌面感就出来了</span>
  .<span>backgroundColor</span>(<span>this</span>.<span>hoverBg</span>)

第二，自由窗口断点。 用户在 PC 上把一个窗口拖窄，它就该从双栏退回单栏——这条线还是靠 on('windowSizeChange') 接住。窗口尺寸回调没接住，用户一拖窗口就白屏，这正是悬崖所在。

V哥的判断：手机能跑 ≠ 电脑好用。 键鼠适配（hover、右键、快捷键、焦点环）是另一层功夫，本文只点题，不展开，避免编造未验证的实测细节。

七、上线自检清单

• 布局是否先定义了断点？没断点的"一折就崩"优先查这里，而不是改业务代码
• 是否在初始化时主动调 getWindowWidthBreakpoint() 校准过一次？
• 是否注册了 window.on('windowSizeChange') 并在回调里刷新断点？
• 页面/Ability 销毁时是否 off('windowSizeChange') 注销了监听？
• 有没有误用 foldStatusChange 做布局主逻辑？（它只建议用于悬停态/相机等功能适配）
• SideBarContainer 窄屏是否用了 Overlay、宽屏是否用了 Embed（或直接 AUTO）？
• GridRow/GridCol 的 columns/span 是否按断点给了阶梯，而非写死？
• Navigation 多端是否用 Auto 模式吃下 600vp 那条单双栏隐线？
• PC/2in1 上的交互组件是否补了 onHover / hoverEffect 悬停反馈？
• 自由窗口拖窄时，双栏能否正确退回单栏（断点回调是否真的接住）？
• 是否只用真机/模拟器覆盖了 折叠态(SM) → 展开态(MD/LG) → 电脑(XL) 三档回归？

参考与出处

本文涉及的事实性信息（API 名称、枚举取值、版本号、官方约束）来自以下官方文档，文中的结构、代码示例、决策流程与自检清单为本人整理编写：

• 一次开发多端部署概览
• 组件布局场景（响应式组件与断点对照）
• 多设备适配屏幕差异（断点 / 窗口尺寸监听 / 折叠状态监听）
• SideBarContainer（SideBarContainerType 枚举）
• Navigation（mode / navBarWidth / 600vp 断点计算）
• GridRow / GridCol（栅格断点与 span）
• Codelab：基于一多能力实现天气应用（MultiWeather，6.1.0 口径）

最后一句话：折叠屏和鸿蒙电脑最反直觉的地方在于——你以为难的是"多写几套布局"，其实难的是"先承认窗口会变、再定义断点"。断点定义好了，代码反而是最省心的那部分。