GridRow + HarmonyOS 屏界手记-03:空状态、窗口边界与大字适配验收【共创稿事节】
展位详情页已经能打开,窗口也能从单栏切到双栏,为什么工程评审仍然没有结束?因为“正常数据、默认字号、完整窗口”是最容易成功的一种组合,而交付现场更容易遇到另一组条件:搜索筛选后的列表为空、当前展位刚被撤销、窗口恰好压在断点附近、系统字体被放大、用户在详情页时把窗口拉宽。这些动作单独看都不复杂,叠在一起就能让界面出现空白、旧详情残留或返回路径混乱。
《屏界手记》前三篇以 VenueFlow 为例逐步建立了工程边界。第一篇用 GridRow/GridCol 的自定义 600vp 断点完成一套数据对应两种布局;第二篇把窄屏详情交给 Navigation/NavPathStack,保留 selectedId 作为业务身份;第三篇在筛选和删除后统一修复选中状态,而不是让列表与详情各自找兜底值。这一篇不再引入新的业务主线,而是对同一套 Booth 展位数据实施交付级验收:明确状态不变量、补齐空结果和失效路径、处理文字缩放时的空间约束,并把可重现的检查顺序固定下来。

一、把“看起来没问题”改成可检查的不变量
VenueFlow 的 Booth 模型沿用 id、title、zone、phase、description 五个字段。示例展位分别是 B-12 木作体验区、B-07 光影剧场、B-19 城市花园、B-23 设计书店。前几篇已经明确不能把数组下标当作业务身份;本篇把这个判断变成四条可以逐次验证的约束。
第一,selectedId 要么为空字符串,要么必须存在于当前可见展位集合,而不只是存在于原始数组。当用户选中了 B-19,然后将筛选条件改为“待确认”,B-19 即使还在原始数组,也已经不属于当前结果。此时保留旧高亮会造成筛选列表与详情割裂。第二,可见结果为零时,不应显示任何旧展位详情,而应明确给出“暂无符合条件的展位”。第三,窄屏的详情是导航状态,宽屏的详情是同一业务状态的布局映射;切宽后不应留下待返回的窄屏详情路径。第四,字符变大或描述变长时,布局可以换行、滚动,但不能用固定高度强行裁掉重要按钮和状态。
这些约束的收益不在于多写几个 if,而在于让故障能落到确切的判定位置。若列表有四项但详情空白,优先检查 selectedId 是否有效;若布局已经是双栏却仍需要返回两次,检查导航栈的清理时机;若 600vp 附近不断抖动,检查是否多个组件同时根据各自宽度反复改写页面状态。真正需要关注的是数据身份、路由和视觉密度三者之间的契约。
对这类界面,我倾向于保留一个非常小的纯函数:接收候选展位与旧 id,返回当前可用的 id。它不读页面宽度,不调用导航接口,也不在内部修改数组。一个纯函数单独测试过边界后,多个事件入口就能复用相同判断。相比在筛选回调、删除回调、窗口回调各写一份“如果找不到就选第一条”,这样的维护成本明显更低。
二、在既有 Booth 上收束筛选与删除事务
下面把示例重心放在 VenueIndex.ets 中可直接复用的状态操作。纯数据方法与页面状态分离,避免把测试条件隐藏在 UI 构建函数里。这里的“待确认”筛选会得到 B-07 与 B-23 两条数据,“已确认”筛选只会得到 B-19;“不存在的阶段”得到空集合。进入详情前必须先确定目标展位属于当前集合。
interface Booth {
id: string;
title: string;
zone: string;
phase: string;
description: string;
}
class BoothRules {
static visible(items: Booth[], phase: string): Booth[] {
return phase === '全部'
? items.slice()
: items.filter((item: Booth) => item.phase === phase);
}
static resolveId(items: Booth[], previousId: string): string {
if (items.length === 0) { return ''; }
return items.some((item: Booth) => item.id === previousId)
? previousId : items[0].id;
}
}
visible() 返回派生数组而不改写源数据;resolveId() 明确处理空集合。这里按原顺序选择第一个候选项,是此示例的产品决策,不应被误认为所有应用都应自动跳选。若真实场景涉及审批、敏感数据和不可逆操作,删除后可以直接清空选择,要求用户再次点击确认。与其让 UI 猜测,不如把回退策略写成团队可讨论的需求条款。
进入页面之后,仍使用前三篇建立的 selectedId 与 NavPathStack。以下完整页面示意汇总关键事务入口与响应式布局;如果已沿用系列前两篇的组件拆分方式,可以将其中的状态方法合并回已有的 VenueIndex。所有改变可见集合的行为最后都经过 repairSelection(),并且在需要时清理路径。此处不另外创建可写的 selectedBooth 副本。
@Entry
@Component
struct VenueIndex {
@State private selectedId: string = 'B-12';
@State private phase: string = '全部';
@State private breakpoint: string = 'xs';
@State private booths: Booth[] = [
{ id: 'B-12', title: '木作体验区', zone: '东展厅', phase: '布展中', description: '从材料触感出发,展示手工木作与互动体验。' },
{ id: 'B-07', title: '光影剧场', zone: '西展厅', phase: '待确认', description: '围绕动态光影构建沉浸式演出空间。' },
{ id: 'B-19', title: '城市花园', zone: '中庭', phase: '已确认', description: '以微型花园展示可持续景观设计。' },
{ id: 'B-23', title: '设计书店', zone: '北展厅', phase: '待确认', description: '精选建筑与视觉设计主题读物。' }
];
private pathStack: NavPathStack = new NavPathStack();
private get visibleBooths(): Booth[] {
return BoothRules.visible(this.booths, this.phase);
}
private get selectedBooth(): Booth | undefined {
return this.visibleBooths.find((b: Booth) => b.id === this.selectedId);
}
private repairSelection(): void {
const next: string = BoothRules.resolveId(this.visibleBooths, this.selectedId);
if (next !== this.selectedId) {
this.selectedId = next;
this.pathStack.clear();
}
}
private applyPhase(value: string): void {
this.phase = value;
this.repairSelection();
}
private removeSelected(): void {
if (!this.selectedId) { return; }
this.booths = this.booths.filter((b: Booth) => b.id !== this.selectedId);
this.repairSelection();
}
private openBooth(id: string): void {
if (!this.visibleBooths.some((b: Booth) => b.id === id)) { return; }
this.selectedId = id;
if (this.breakpoint === 'xs') {
this.pathStack.pushPath({ name: 'BoothDetail', param: id });
}
}
@Builder
private detailPane() {
if (this.selectedBooth !== undefined) {
Column({ space: 12 }) {
Text(this.selectedBooth!.title).fontSize(26).fontWeight(FontWeight.Bold)
Text(`${this.selectedBooth!.id} · ${this.selectedBooth!.zone}`)
Text(this.selectedBooth!.phase).fontColor('#17846B')
Text(this.selectedBooth!.description).fontSize(16)
}.padding(16).width('100%')
} else {
Column({ space: 12 }) {
Text('暂无符合条件的展位').fontSize(20)
Button('查看全部').onClick(() => this.applyPhase('全部'))
}.padding(20).width('100%')
}
}
@Builder
private detailDestination(name: string) {
NavDestination() {
Scroll() { this.detailPane() }
}.title('展位详情')
}
build() {
Navigation(this.pathStack) {
Scroll() {
Column({ space: 16 }) {
Text('展位视界').fontSize(28).fontWeight(FontWeight.Bold)
Row({ space: 10 }) {
ForEach(['全部', '布展中', '待确认', '已确认'], (value: string) => {
Button(value).onClick(() => this.applyPhase(value))
})
}
GridRow({ columns: 12, gutter: { x: 16, y: 16 },
breakpoints: { value: ['600vp'], reference: BreakpointsReference.WindowSize } }) {
GridCol({ span: { xs: 12, sm: 5 } }) {
Column({ space: 10 }) {
Text(`全部展位 · ${this.visibleBooths.length}`)
ForEach(this.visibleBooths, (b: Booth) => {
Column({ space: 6 }) {
Text(`${b.id} ${b.title}`)
Text(`${b.zone} · ${b.phase}`).fontSize(14)
}.padding(14).width('100%')
.backgroundColor(b.id === this.selectedId ? '#DDF4EC' : '#FFFFFF')
.onClick(() => this.openBooth(b.id))
}, (b: Booth) => b.id)
if (this.visibleBooths.length === 0) { Text('暂无符合条件的展位') }
Button('移除当前选中').onClick(() => this.removeSelected())
}.width('100%')
}
GridCol({ span: { xs: 12, sm: 7 } }) {
if (this.breakpoint !== 'xs') { this.detailPane() }
}
}.onBreakpointChange((bp: string) => {
this.breakpoint = bp;
if (bp !== 'xs') { this.pathStack.clear(); }
})
}.padding(20).width('100%')
}
}.navDestination(this.detailDestination).width('100%')
}
}
这段示例把状态入口、导航目的地与响应式布局放在同一页,方便检查数据流。它是可用于工程合并的示例代码,目标 SDK、主题和实际布局仍需在 DevEco Studio 中完成类型检查及设备回归。其关键是每次变更后都从相同的 visibleBooths 判定状态。如果筛选从“全部”切换成“待确认”,原先的 B-12 会调整为 B-07;如果再删除 B-07,会调整为 B-23;继续删除 B-23,选中 id 变为空字符串,详情应显示空视图。此时即使旧路由参数里还有 B-07,也不能再从旧对象绘制详情。
三、空态、字号与窗口断点要协同设计
页面层的空态不是简简单单写一个“暂无数据”就结束。它首先需要避免不安全的非空断言,然后要明确空态出现在哪一层:搜索无结果时,列表区域显示空态;删除全部展位时,根页面和详情目的地都要有一致的说明;如果用户正停留在窄屏详情,删除导致当前 id 失效,则应清栈回根,而不是允许“删除成功”之后继续看已不存在的详情。

构建布局时,可以用 if (this.selectedBooth) 的条件分支控制详情卡片,另一支使用说明文字和“查看全部”按钮,而不是始终访问 this.selectedBooth!。当用户切回“全部”,仍由 repairSelection() 选择合法项。列表的 ForEach 始终使用 b.id 作为 key;无论筛选、排序还是删除,身份语义不会跟随索引漂移。这也使最终验收可以检查两个完全独立的层次:数据是否选对,UI 是否画对。
断点仍采用本系列的 600vp,不另建一套宽屏页面。GridRow({ columns:12, gutter:{x:16,y:16}, breakpoints:{value:['600vp'], reference:BreakpointsReference.WindowSize} }) 对应 GridCol({ span:{xs:12,sm:5} }) 和 GridCol({ span:{xs:12,sm:7} })。要注意这里判断的是应用窗口尺寸,不是设备市场名称。带自由窗口功能的平板上,一台设备可以在几秒内跨越断点多次,开发时别把“检测到平板”当成宽屏条件。
大字环境下的难点更具隐蔽性。以 B-19 “城市花园”为例,标题放大后可能由一行变成两行,阶段标签、操作按钮就需要自然下移。字体大小应采用可以随着系统设置和产品无障碍策略调整的设计,容器不强制固定卡片高度。对于较长的 description,详情可置于 Scroll 内,给正文足够高度;对于操作区,按钮需要完整的可点击区域,不能靠缩小字号维持视觉上的一行整齐。若产品允许用户在系统大字模式下操作,验收时必须实际打开目标设备的对应设置,而不能只把设计稿放大百分比。
窗口尺寸与文字密度存在交叉问题。原本处于双栏的页面可能在增大字号后仍达到 600vp,但右栏的实际可用宽度已经明显不足。此时要复查文字换行和按钮排列;必要时由设计重新提高断点,或者减少每张卡片里的次要信息,而不是在回调里偷偷重置 selectedId。断点负责结构,排版负责可读性,业务状态负责身份,三件事分开才能找到真实的修复位置。
四、把回归顺序固定成一张工程矩阵
为了避免只在某个开发者熟悉的设备上顺手点几下,我把验收拆成六组。每组都指定输入操作、应该观察的状态,以及失败时优先检查的代码位置。没有填入所谓“已通过”的结果;下面是一套可由项目成员在安装目标 SDK 的 DevEco Studio 和设备上逐项执行的验收流程。
| 组合 | 操作 | 预期状态 | 优先检查点 |
|---|---|---|---|
| 窄窗 + 全部 | 选 B-19 再进入详情 | 城市花园、中庭、已确认 | selectedId 与路由参数 |
| 宽窗 + 全部 | 宽度越过 600vp | 5/7 双栏且仍选 B-19 | GridRow 断点、清栈时机 |
| 窄窗 + 待确认 | 从 B-19 切换筛选 | 选中 B-07,B-19 不残留 | resolveId() |
| 窄窗 + 删除 | 连续删除 B-07、B-23 | 无结果,显示明确空态 | repairSelection() |
| 边界宽度 | 在 590vp 与 610vp 间改变窗口 | 布局切换,业务 id 不跳变 | onBreakpointChange 与窗口事件 |
| 大字号 + 长文案 | 增大字体后打开详情并滚动 | 标题可换行、按钮可操作 | Scroll、行高与组件尺寸 |
验证时不要把“没有报错”当作全部通过,尤其应区分两类异常:状态错误是选中对象不匹配、已删除对象仍展示;布局错误是正确文本存在却被裁切、遮挡或难以点击。前一类优先检查 BoothRules 和状态变更入口,后一类才需要检查 GridRow 和视觉约束。若混在一起处理,很容易引入“为了修复布局而刷新数据”的反效果。
实际写回归记录时,推荐为每条用例保留窗口宽度范围、筛选条件、操作序列与文本结果,而不是只截一张好看的最终图片。遇到偶发故障,至少能重放“窄窗选中 B-07 → 删除 → 拉宽 → 返回”这一整条交互链。此前系列的导航清栈策略也应在这种序列中检查:当下发的数据使 id 失效时,必须先恢复合法选择,再允许新的详情入口;不要在 aboutToAppear 中随意操作导航栈,官方也明确提示该时机可能导致页面尚未完成构建时的跳转问题。

五、收尾是删掉重复状态,而不是继续加兼容分支
这一套工程最终留下三类资产。第一类是业务身份:四个 Booth 的稳定 id 和筛选后仍合法的 selectedId。第二类是结构规则:一个 600vp 断点与统一的窄屏导航栈;它们定义“怎么呈现”,不保存“用户选了什么”。第三类是验收契约:正常、空列表、删除、缩放、大字、窗口切换都必须能重放。四篇文章按此顺序推进,正好覆盖需求、初版、故障修复和最后的边界验收。
工程上还留有明确范围:本例使用本地静态展位数据,未引入网络请求、数据库和账号权限,不需要新增系统敏感权限;复杂多层导航、窗口恢复策略和后台数据刷新需要在真实产品中扩展。对于系统 API,GridRow/GridCol 与 onBreakpointChange 的适配行为可参照华为官方 GridRow 参考;Navigation/NavPathStack 使用条件与页面状态注意事项可参照 Navigation 参考。本系列选择可追溯的公开接口,不把宣传层面的“平行视界”等设备能力当成可以直接调用的通用 SDK 方法。
结束一个连载的合理方式,不是宣称所有设备已经自动适配,而是让下一位开发者拿到页面之后知道三件事:该改哪个状态、该测哪些边界、发现错位该沿哪条路径追查。VenueFlow 的四篇实现由此形成一个能被审查、测试与持续演进的小型响应式工程闭环。
更多推荐

所有评论(0)