这一篇做质量复盘。页面在理想数据下好看不难，难的是长标题不挤压、空列表不尴尬、固定底部栏不遮挡、大屏不失控。这里把疆域纪行里最常见的布局稳定性问题集中拆一遍。

项目落点：

• 长文本处理：maxLines()、textOverflow()、layoutWeight()
• 固定栏避让：主内容 bottom padding、详情内容 bottom padding
• 空状态：EmptyCard()
• 图片容器：固定宽高 + ImageFit.Cover
• 设备声明：phone、tablet、2in1

读完这一篇，你可以复用一份发布前视觉检查清单，尤其适合内容多、卡片多、图片多的 HarmonyOS App。

真正的 App 不只跑在“理想数据”上

很多页面在 Demo 数据下很好看，一到真实内容就出问题：

• 地名太长，标题挤出卡片。
• 摘要太长，卡片高度不一致。
• 筛选无结果，页面空白。
• 固定底部栏盖住最后一段内容。
• 平板上页面过宽，阅读困难。
• 图片比例不同，卡片忽高忽低。

《疆域纪行》虽然是 MVP，但已经处理了不少这类问题。这一篇不讲炫酷效果，专门讲稳定性。

压测内容	容易出现的问题	首选处理方式
长地名	挤压按钮或图标	layoutWeight + constraintSize
长摘要	卡片高度失控	maxLines + 省略
空收藏	用户以为功能坏了	空状态说明下一步
固定底栏	遮住最后内容	滚动区增加 bottom padding

这些问题看起来琐碎，但它们正是 Demo 和可用 App 的分界线。

长标题：maxLines 和 textOverflow 要成套出现

列表卡片中，标题一般这样写：

Text(item.title)
  .fontSize(17)
  .fontColor('#1F2D36')
  .fontWeight(FontWeight.Bold)
  .maxLines(1)
  .textOverflow({ overflow: TextOverflow.Ellipsis })
  .layoutWeight(1)

maxLines(1) 限制行数，textOverflow 显示省略，layoutWeight(1) 让标题占用剩余空间。

但仅有这些还不够。父容器通常还需要：

.constraintSize({ minWidth: 0 })

否则在 Row 布局中，文本可能不愿意收缩，导致右侧按钮被挤出屏幕。

一句经验：只要 Row 里有“左侧长文本 + 右侧按钮”，就要特别检查 layoutWeight 和 constraintSize。

摘要文本：不要无限撑高卡片

卡片摘要一般控制在两行：

Text(item.summary)
  .fontSize(12)
  .fontColor('#56636B')
  .maxLines(2)
  .textOverflow({ overflow: TextOverflow.Ellipsis })

内容型 App 很容易有长摘要。如果不限制，某些卡片会特别高，列表节奏会被破坏。两行摘要是一个平衡点：既能展示信息，也能保持列表可扫读。

详情页正文则不同，应该允许完整阅读：

Text(item.summary)
  .fontSize(14)
  .fontColor('#34424B')
  .lineHeight(23)

同一段内容在不同页面要有不同策略：

• 列表页：压缩、扫读。
• 详情页：完整、舒适。

空状态：让用户知道下一步

项目里复用了 EmptyCard：

this.EmptyCard('没有匹配内容', '可以切换地区、主题或清空搜索关键词后再试。')

收藏为空时：

this.EmptyCard('还没有收藏', '在探索和详情页点收藏，离线旅行清单就会出现在这里。')

搜索无结果时：

this.EmptyCard('没有找到相关内容', '可以试试“赛里木湖”“喀什”“大盘鸡”“北疆”等关键词。')

好的空状态不只是“没有数据”，而是告诉用户为什么没有，以及下一步可以做什么。

对内容型 App 来说，空状态至少要覆盖：

• 收藏为空。
• 搜索无结果。
• 筛选无结果。
• 本地数据读取失败后的兜底。

固定底部栏：内容底部要留白

详情页底部有固定操作栏：

Row({ space: 12 }) {
  Button(...)
  Button(...)
}
.padding({ left: 18, right: 18, top: 12, bottom: 18 })
.backgroundColor('#FFFFFC')

为了避免滚动内容被按钮遮住，详情内容区设置了较大的 bottom padding：

.padding({ left: 18, right: 18, top: 18, bottom: 188 })

这是移动端布局里非常常见的坑。只要有固定底部按钮、底部导航、悬浮操作栏，就一定要给滚动内容留出底部空间。

否则最后一条注意事项、免责声明、输入框很可能被遮住。

底部导航：主内容也要预留空间

主 Shell 中内容区域：

.padding({ left: 16, right: 16, top: 18, bottom: 92 })

bottom: 92 是给底部导航留的空间。这个值不一定通用，但思路通用：固定导航和滚动内容必须协商空间。

如果后续适配安全区，可以进一步结合系统安全区域或统一布局常量。

图片容器：固定尺寸减少跳动

卡片图片都设置了明确尺寸：

Image(item.image)
  .width(92)
  .height(82)
  .objectFit(ImageFit.Cover)

横向卡片：

.width(124)
.height(94)

详情头图：

.height(244)

固定图片容器能减少布局跳动。尤其是本地图片数量多、比例差异大时，如果图片高度随内容自然变化，页面会很难控制。

筛选 Chip：选中状态要明显

探索页有很多筛选 Chip：

this.ExploreFilterChip('north', '北疆', 'region')
this.ExploreFilterChip('south', '南疆', 'region')
this.ExploreFilterChip('connector', '连接地带', 'region')

Chip 的选中状态不仅要变颜色，还要真正驱动内容变化。项目里通过状态控制：

@State exploreRegion: string = 'all';
@State exploreTheme: string = 'all';

再由 getExploreAtlasItems() 统一计算结果。这样不会出现“按钮看起来选中了，但列表没变”的问题。

平板和 2in1 的预留

module.json5 中声明了：

"deviceTypes": [
  "phone",
  "tablet",
  "2in1"
]

当前 MVP 主要是竖向信息流，但已经注意到一些大屏问题：

• 文本行宽不能无限拉长。
• 图片要保持合理裁切。
• 卡片不要因为屏幕宽就变得过大。
• 路线时间轴在平板上可以升级为更宽松布局。

后续真正做平板适配时，可以考虑：

• 探索页左侧筛选，右侧内容列表。
• 路线页多列卡片。
• 详情页限制正文最大宽度。
• 收藏页使用两列布局。

先声明设备支持不代表适配完成，但它提醒我们在写布局时不要只盯着一台手机。

视觉稳定性检查清单

这个项目在发布前可以按下面清单检查：

• 首页 Hero 文字在浅色图片上是否仍可读。
• 热门目的地横向滚动是否顺滑。
• 探索页多个筛选条件组合是否正常。
• 搜索无结果是否出现空状态。
• 收藏为空是否有引导。
• 详情页底部内容是否被操作栏遮挡。
• 长标题是否挤压收藏按钮。
• 路线时间轴长住宿名称是否溢出。
• 图片缺失或替换时是否有颜色兜底。
• 深浅色模式下启动窗口是否突兀。

这些检查不复杂，但能显著提升成品感。

验证清单

检查项	操作方式	通过标准
标题和摘要不会挤压右侧按钮	对照项目文件或真机/模拟器操作	结果符合文章描述
空收藏和无搜索结果都有明确文案	对照项目文件或真机/模拟器操作	结果符合文章描述
详情页最后内容不被底部栏遮挡	对照项目文件或真机/模拟器操作	结果符合文章描述
图片比例不同但卡片高度稳定	对照项目文件或真机/模拟器操作	结果符合文章描述
平板上正文不会无限拉宽	对照项目文件或真机/模拟器操作	结果符合文章描述

常见问题和处理

问题现象	优先排查	处理方式
长标题把按钮挤没	给文本 layoutWeight 并设置 minWidth 0	配合 maxLines 和省略
空状态像页面坏了	补充原因和下一步建议	不要只写“暂无数据”
大屏阅读太宽	给内容区限制最大宽度	路线页可升级多列布局

本篇小结

适配和稳定性不是最后才做的“擦边工作”，而是贯穿页面开发全过程：

• 长文本要限制和省略。
• Row 中长文本要配合 layoutWeight 和 constraintSize。
• 空状态要给用户下一步提示。
• 固定底部栏必须给滚动内容留空间。
• 图片容器要有稳定尺寸。
• 筛选状态必须同时影响样式和内容。
• 平板适配要从布局习惯上提前预留。

下一篇是本系列收官：从构建配置、发布材料、隐私说明和项目复盘角度，看看一个 HarmonyOS 单机 App 如何走向可发布。