【笔下生辉｜16】HarmonyOS ArkTS 多设备布局实战：适配手机、平板和 PC/2in1 的窗口变化

实际做 HarmonyOS 5.0+ 应用时，多设备适配最容易出问题的地方不是“有没有写响应式布局”这句话，而是窗口变化发生以后，页面到底由谁感知、谁保存状态、谁决定布局、谁处理安全区。笔下生辉这套源码把适配拆成了三个可复核的点：BreakpointSystem 用 mediaquery 产出 sm、md、lg 断点，EntryAbility 把顶部和底部避让区写进 AppStorage，各页面再结合 @StorageLink 与 onAreaChange 决定列表、网格、宽屏详情和底部导航的表现。

本文只讨论源码中已经存在、可以逐行复核的实现。项目包名标记为 com.jiaweikang.one17。需要先说明边界：当前 Index.ets 虽然保留了侧边导航分支，但它的条件把 sm、md、lg 都归入底部导航分支；由于 BreakpointSystem 只会写入这三个值，所以侧边导航分支在当前代码下不会被触达。这个点很重要，因为它决定了本文不能把“已完成 PC 侧边栏导航切换”当成既有能力，只能把它作为源码审查中发现的后续优化项。

1. 这篇文章解决什么问题

笔下生辉是一个面向客家谚语、分类、题库和学习统计的 HarmonyOS 应用。它的页面不只是简单列表：首页有分类入口和推荐内容，谚语列表在宽屏下需要从单列变成多列，详情页在大窗口下要拉开信息区和内容区，分类页需要根据容器宽度改变卡片比例，考试结果页和主导航还要避开系统底部手势区。把这些需求混在单个页面里硬写，会得到一堆难维护的 if；源码里更稳定的做法，是把设备级断点、容器级宽度、安全区这三类信号分开。

本文会按真实代码梳理四个问题：

这套分工的价值在于：断点变化可以统一维护，页面宽度仍由页面自己测量，安全区不需要每个页面直接访问窗口对象。这样写不会把 Ability 生命周期、ArkUI 页面状态和业务卡片布局揉在一起。

2. 先看源码边界：断点不是页面自己猜出来的

BreakpointSystem.ets 是这套适配链路的入口。它没有把窗口宽度判断散落到每个页面，而是用 @kit.ArkUI 的 mediaquery 注册三条监听规则：

import { mediaquery } from '@kit.ArkUI';

export type BreakpointType = 'sm' | 'md' | 'lg';

export class BreakpointSystem {
private static currentBp: BreakpointType = 'sm';
private static smListener: mediaquery.MediaQueryListener | null = null;
private static mdListener: mediaquery.MediaQueryListener | null = null;
private static lgListener: mediaquery.MediaQueryListener | null = null;

static register(): void {
this.smListener = mediaquery.matchMediaSync('(width<=600vp)');
this.mdListener = mediaquery.matchMediaSync('(600vp<width<=840vp)');
this.lgListener = mediaquery.matchMediaSync('(840vp<width)');

this.smListener.on('change', result => {
if (result.matches) {
this.update('sm');
}
});
this.mdListener.on('change', result => {
if (result.matches) {
this.update('md');
}
});
this.lgListener.on('change', result => {
if (result.matches) {
this.update('lg');
}
});

if (this.smListener.matches) {
this.update('sm');
} else if (this.mdListener.matches) {
this.update('md');
} else {
this.update('lg');
}
}
}

这段代码可以得出三个确定事实。

第一，源码里的断点只有 sm、md、lg 三种。sm 覆盖 width<=600vp，md 覆盖 600vp<width<=840vp，lg 覆盖 840vp<width。因此文章不能额外声称源码实现了更多设备等级，例如独立的 xl、pc 或 fold。

第二，断点由媒体查询监听驱动。页面不需要主动轮询窗口宽度，监听器在匹配结果改变后通过 update() 写入状态。

第三，注册后会立即执行一次初始判断。这个初始判断对启动态很关键：如果没有它，页面第一次构建时可能一直停在默认 sm，只有下一次窗口变化后才进入正确布局。

3. 用 AppStorage 传播 currentBreakpoint

断点更新的真正出口是 update(bp)。源码里它同时维护类内部字段和 AppStorage：

private static update(bp: BreakpointType): void {
this.currentBp = bp;
AppStorage.setOrCreate<string>('currentBreakpoint', bp);
}

static current(): BreakpointType {
return this.currentBp;
}

static select<T>(sm: T, md: T, lg: T): T {
if (this.currentBp === 'sm') {
return sm;
}
if (this.currentBp === 'md') {
return md;
}
return lg;
}

这里的工程取舍比较清楚。BreakpointSystem.current() 和 select() 适合普通工具代码同步读取当前断点；页面层更常用的是 @StorageLink('currentBreakpoint')，因为它可以让 ArkUI 页面在值变化后重新渲染。对多设备布局来说，后者比在页面里手动保存一个普通字段更可靠。

如果页面自己调用 BreakpointSystem.current()，它只能读到当前值；如果值之后改变，页面还要自己处理刷新。源码采用 AppStorage 的好处是把断点变成了一个跨页面响应式信号。

4. EntryAbility 负责注册和清理，不把监听器留给页面

断点监听器的生命周期不能随便放。放在某个页面里，用户切换页面以后可能出现重复注册、漏清理、页面销毁后仍然回调的问题。笔下生辉把注册放在 EntryAbility.onCreate()，把清理放在 onDestroy()：

import { BreakpointSystem } from 'libraryb/src/main/ets/utils/BreakpointSystem';

export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
UserDataManager.init(this.context);
AppStorage.setOrCreate<number>('currentTabIndex', 0);
AppStorage.setOrCreate<number>('favoriteTabIndex', 0);
AppStorage.setOrCreate<number>('topAvoidAreaHeightPx', 0);
AppStorage.setOrCreate<number>('navigationIndicatorHeightPx', 0);
BreakpointSystem.register();
}

onDestroy(): void {
BreakpointSystem.unregister();
}
}

这个位置是合理的：应用入口创建时注册设备级监听，Ability 销毁时释放。这样页面只消费状态，不拥有监听器。对一套文章应用来说，页面数量越多，这个边界越重要，因为首页、题库页、详情页、分类页都可能需要同一个断点。

需要注意的是，源码里的 unregister() 会对非空监听器调用 off('change')。这能避免监听器在 Ability 生命周期结束后继续工作。实际项目还可以进一步把 listener 置空，但当前源码已经表达出清理意图。

5. 安全区是第二条适配主线

多设备适配不只是宽度。HarmonyOS 设备上状态栏、导航条、手势指示条、沉浸式窗口都会改变可用区域。笔下生辉在 EntryAbility.onWindowStageCreate() 中拿到 mainWindow，并尝试开启全屏布局，同时读取避让区：

const mainWindow = windowStage.getMainWindowSync();
mainWindow.setWindowLayoutFullScreen(true);
mainWindow.setWindowSystemBarProperties({
statusBarContentColor: '#000000',
navigationBarContentColor: '#000000'
});

this.updateTopAvoidAreaHeight(mainWindow);
this.updateNavigationIndicatorHeight(mainWindow);
mainWindow.on('avoidAreaChange', data => {
this.updateTopAvoidAreaHeight(mainWindow);
this.updateNavigationIndicatorHeight(mainWindow);
});

源码后续把顶部避让区写进 topAvoidAreaHeightPx，把底部导航指示区域和系统区域取较大值后写进 navigationIndicatorHeightPx。页面侧不直接访问 Window，只通过 @StorageLink 消费这两个数值。

这个设计避免了一个常见问题：页面为了计算底部 padding 到处读取窗口安全区，最后每个页面处理单位转换和默认值的逻辑都不一致。现在入口层统一写入 px，页面层按需要转换为 vp，再和最小 padding 做 Math.max()。

6. Index：底部导航已经做安全区避让，但侧边导航分支目前不可达

Index.ets 里有三类共享状态：

@StorageLink('currentBreakpoint') currentBp: string = 'sm';
@StorageLink('topAvoidAreaHeightPx') topAvoidAreaHeightPx: number = 0;
@StorageLink('navigationIndicatorHeightPx') navigationIndicatorHeightPx: number = 0;
@StorageLink('currentTabIndex') currentIndex: number = 0;

它还定义了顶部和底部安全区转换：

private bottomSafePadding(): number {
return Math.max(Sizes.BOTTOM_NAV_MIN_PADDING, px2vp(this.navigationIndicatorHeightPx));
}

private topSafePadding(): number {
return Math.max(Sizes.PADDING_SMALL, px2vp(this.topAvoidAreaHeightPx));
}

private bottomNavHeight(): number {
return Sizes.TAB_BAR_HEIGHT + this.bottomSafePadding();
}

这说明主页面底部导航不是固定贴底，而是把系统底部区域纳入高度计算。对手势导航设备、小窗模式和不同设备底部安全区来说，这比写死 56vp 更稳。

但 Index.ets 里有一个必须如实说明的源码边界。构建逻辑中，当前判断把 sm、md、lg 都归入底部导航分支：

if (this.currentBp === 'sm' || this.currentBp === 'md' || this.currentBp === 'lg') {
Column() {
Stack() {
this.buildCurrentPage()
}
.layoutWeight(1)

this.buildBottomNav()
}
} else {
Row() {
this.buildSideNav()
this.buildCurrentPage()
}
}

由于 BreakpointSystem 只会写入 sm、md、lg，else 分支当前不会进入。这不是文章推断，而是由两个文件共同决定的事实。因此笔下生辉当前主导航的真实状态是：底部导航支持所有断点并处理安全区；侧边导航代码存在，但没有被当前断点条件触发。后续如果要让 PC/2in1 使用侧边导航，可以把条件收窄为 sm、md 使用底部导航，lg 使用侧边导航，或者增加更明确的窗口形态判断。

7. 列表页：断点加 pageWidth 才决定是否网格化

BankListPage.ets 没有只依赖 currentBreakpoint。它还维护页面实际宽度：

@StorageLink('currentBreakpoint') currentBp: string = 'sm';
@State private pageWidth: number = 360;

private useGridLayout(): boolean {
return this.currentBp === 'lg' && this.pageWidth >= 700;
}

页面通过 onAreaChange 更新 pageWidth。这一步非常实际，因为在平板、折叠屏、PC/2in1 窗口中，设备级断点和当前容器宽度并不总是等价。一个 lg 断点下的分屏窗口可能并没有足够空间展示三列卡片；反过来，某些中等窗口如果内容区被侧栏、弹窗或系统区域挤压，也需要回退到列表。

源码里当 useGridLayout() 为真时使用 Scroll + Flex 包裹卡片，并把单项宽度设为约 32%；否则使用 List 和 BankCard。这就是笔下生辉列表适配的核心：不是“宽屏必定网格”，而是“断点为大屏且实际页面宽度达到阈值才网格”。

迁移到其他 HarmonyOS 页面时，可以保留这个判断模式：

@StorageLink('currentBreakpoint') currentBp: string = 'sm';
@State private pageWidth: number = 360;

private canUseThreeColumn(): boolean {
return this.currentBp === 'lg' && this.pageWidth >= 700;
}

build() {
Column() {
if (this.canUseThreeColumn()) {
this.buildGridContent();
} else {
this.buildListContent();
}
}
.onAreaChange((oldArea, newArea) => {
const width = Number(newArea.width);
if (width > 0) {
this.pageWidth = width;
}
})
}

这段模式的边界也很清晰：currentBreakpoint 判断全局窗口级别，pageWidth 判断当前组件可用空间。两个条件同时满足，才进入更激进的布局。

8. 首页、题库、统计页复用同一类判断

从源码看，HomePage.ets、ExamTab.ets、LearningStatsPage.ets 都采用类似策略：用 @StorageLink('currentBreakpoint') 获取断点，用 @State pageWidth 保存页面宽度，再用 currentBp === 'lg' && pageWidth >= 700 作为网格或宽屏布局的开关。

这种重复不是坏事。它说明项目把布局策略保持在页面局部，而不是过早抽象成一个全局万能布局服务。首页、题库和统计页的卡片内容不同，阈值现在恰好一致，但它们各自仍有独立调整空间。等到多个页面的布局计算完全稳定以后，再考虑把阈值常量抽到共享层会更稳。

可以把这类页面的判断整理成一个决策表：

这个表也解释了为什么源码没有简单地把 md 当成平板布局。平板、折叠屏和 PC 小窗都可能出现中间状态，pageWidth 能避免布局被断点误判。

9. BankDetailPage：宽屏详情页不是换一层容器这么简单

详情页的多设备适配更容易出视觉问题。列表页最多是单列和多列，详情页还要处理标题、收藏、内容、相关信息和底部区域。BankDetailPage.ets 的判断是：

@StorageLink('currentBreakpoint') currentBp: string = 'sm';
@StorageLink('navigationIndicatorHeightPx') navigationIndicatorHeightPx: number = 0;
@State private pageWidth: number = 360;

private useWideLayout(): boolean {
return this.currentBp === 'lg' && this.pageWidth >= 700;
}

private bottomSafePadding(): number {
return Math.max(Sizes.BOTTOM_NAV_MIN_PADDING, px2vp(this.navigationIndicatorHeightPx));
}

源码里宽屏布局会调整卡片高度，例如宽屏时使用更高的展示区域，窄屏时保持更紧凑。HakkaBankPage.ets 只是把固定谚语 ID 传给 BankDetailContent({ fixedBankId: 'b_hakka' })，因此客家专题详情不需要复制一份适配逻辑。这个复用点值得保留：专题入口可以不同，内容页适配仍由同一个组件负责。

详情页的关键不是“屏幕大就塞更多东西”，而是先确认容器宽度足够，再改变阅读节奏。对谚语类应用来说，太早进入双栏会让文字阅读路径变散；太晚进入宽屏又浪费空间。lg && pageWidth >= 700 是一个保守阈值，能覆盖大多数平板横屏和 PC/2in1 窗口，同时不给手机横屏强行套大屏布局。

10. CategoryPage：按容器宽度控制卡片比例

CategoryPage.ets 没有接入 currentBreakpoint，它直接用页面宽度决定卡片占比：

@State private pageWidth: number = 360;

private itemWidth(): string {
return this.pageWidth >= 720 ? '24%' : '48%';
}

这个实现适合分类卡片，因为分类页更关心“当前行能放几张卡片”，不一定需要知道全局断点。48% 基本对应两列，24% 基本对应四列，中间留给 Flex 间距和换行。页面通过 onAreaChange 维护宽度，Flex 再负责自动换行。

如果把分类页也强行接入断点，反而可能增加错误：一个 lg 设备上的窄窗口也许只能放两列；一个 md 宽度的平板竖屏也可能比普通手机更适合更宽松的两列卡片。源码当前做法简单，但契合分类页的实际布局目标。

11. ExamResultPage：结果页重点在底部可达性

考试结果页不需要复杂分栏，但它需要保证底部操作不被系统导航区遮挡。ExamResultPage.ets 使用 @StorageLink('navigationIndicatorHeightPx') 读取底部避让值，再通过 bottomSafePadding() 和页面底部间距配合，保证结果页按钮、记录提示或返回操作能被触达。

这类页面的适配标准和列表页不同。列表页关心信息密度，结果页关心操作安全。尤其在考试完成后，用户通常会点击继续练习、查看错题、返回首页等动作，如果底部按钮进入系统手势区域，真实设备上会出现误触或不可达。

因此，判断一个页面是否做好多设备适配，不能只看它有没有 currentBreakpoint。像 ExamResultPage 这种结果页，安全区处理比网格化更重要。

12. 验证方式：不要只在一个预览窗口里看效果

这套源码适配链路至少要按三类信号验证。

建议的本地检查路径是：先在手机宽度看底部导航和单列列表，再把窗口拉到 840vp 以上验证列表和详情页的宽屏策略，最后在 PC/2in1 或模拟器小窗里反复缩放，确认 pageWidth 阈值比单纯断点更稳。

13. 常见问题和修复方向

其中最值得优先处理的是侧边导航条件。当前代码保留了侧边导航构建函数，但条件不可达。这个问题不会影响底部导航的可用性，却会影响对“PC/2in1 导航形态”的声明。上线材料或技术文章中必须按真实状态表述，避免把备用代码说成已经生效。

14. 可以落地的改进建议

如果后续要继续增强笔下生辉的多设备布局，建议按风险从低到高推进。

第一步，把 Index.ets 的导航条件改清楚。例如：

private useSideNav(): boolean {
return this.currentBp === 'lg';
}

build() {
if (this.useSideNav()) {
Row() {
this.buildSideNav()
this.buildCurrentPage()
}
} else {
Column() {
Stack() {
this.buildCurrentPage()
}
.layoutWeight(1)

this.buildBottomNav()
}
}
}

这段只是改进方向，不是当前源码已经采用的实现。它的好处是让导航形态和断点关系可读，也避免 else 分支长期不可达。

第二步，把 700、720、840 等关键阈值沉淀成命名常量。现在这些阈值散落在页面和断点系统中，仍然可以读懂；当页面继续增加时，建议使用类似 AdaptiveLayoutTokens.WIDE_PAGE_MIN_WIDTH 的方式集中说明。

第三步，给 lg 下的小窗回退做更明确的验证。源码已经用 pageWidth 处理了这一点，但验收时要把“设备是大屏，但窗口是窄的”单独列出来。PC/2in1 用户经常把窗口拖成半屏，单纯看设备类型并不够。

15. 小结

笔下生辉这篇多设备布局的源码价值，在于它没有把适配写成一句笼统的“大屏适配”。BreakpointSystem 负责全局断点，EntryAbility 负责生命周期和安全区，页面通过 @StorageLink、onAreaChange、pageWidth 决定具体布局。列表页、首页、题库页、统计页用 lg && pageWidth >= 700 进入网格或宽屏状态；详情页用同样思路控制阅读区域；分类页则直接按容器宽度调整卡片比例；结果页重点处理底部安全区。

同时，源码也暴露了一个明确边界：Index.ets 的侧边导航分支当前不会被 sm、md、lg 触达。工程文章应该把这种边界写清楚，因为真实可复核比说得完整更重要。对于 HarmonyOS 5.0+ 多设备开发，可靠的适配不是多写几个分支，而是让断点、容器宽度、安全区各自承担清晰职责，并在窗口变化时保持页面状态可预测。

本文内容基于笔下生辉项目中 BreakpointSystem.ets、EntryAbility.ets、Index.ets、BankListPage.ets、BankDetailPage.ets、CategoryPage.ets、ExamResultPage.ets、HakkaBankPage.ets 等真实源码整理；部分内容由 AI 辅助生成，最终以源码复核和人工校对为准。本篇文章使用独立封面 media/cover.png，应用合集封面复用 06-笔下生辉/media/collection-cover.png。