目录前言三大核心组件概述2.1 Column —— 弹性列布局2.2 List —— 虚拟滚动列表2.3 Navigation —— 页面导航容器列表—导航协作模式的设计思想3.1 为什么需要协作布局3.2 数据驱动 vs DOM 操作3.3 状态驱动的页面切换项目搭建与配置4.1 工程结构总览4.2 主题色系统设计4.3 数据类型定义Index.ets 完整代码逐段解析5.1 数据组织列表数据源设计5.2 状态体系State currentDetail 驱动页面切换5.3 列表页首页的 Column 分层结构5.4 标题区域——品牌呈现5.5 搜索操作栏——Row 水平布局5.6 List 虚拟滚动列表——核心渲染区域5.7 ListItem 内容模板——图标 标题 箭头5.8 详情页的 Scroll Column 双布局组合5.9 详情内容区的多层次 Column 嵌套5.10 Navigation 容器属性详解Navigation 导航模式深度解析6.1 Navigation 工作原理6.2 标题模式Mini vs Full6.3 返回按钮的联动控制6.4 NavRouter 与条件渲染的比较List 虚拟滚动机制详解7.1 虚拟滚动的核心原理7.2 缓存策略cachedCount7.3 性能对比List vs Scroll ColumnColumn 布局深入实践8.1 Column 的嵌套策略8.2 layoutWeight 的空间分配8.3 Column Row 的组合模式编译与调试经验9.1 List 子组件限制9.2 NavRouter 废弃的迁移路线9.3 NavigationTitleMode 类型约束效果展示与交互流程10.1 列表首页布局10.2 详情页布局10.3 典型交互流程性能分析与最佳实践11.1 列表渲染性能11.2 最佳实践清单扩展方向12.1 搜索过滤功能12.2 分组列表——Section 组件12.3 路由传参与多级导航总结前言在移动应用开发中「列表页 → 详情页」 是最经典、最高频的页面模式之一。无论是新闻客户端、电商应用、社交平台还是企业工具几乎每一个应用都包含「条目列表 点击查看详情」的交互流程。在 HarmonyOS NEXT 的 ArkUI 框架中这一模式可以通过 Column List Navigation 三个核心组件的协作来优雅实现Column 负责垂直布局的组织——标题、搜索栏、列表内容、底部状态全部由 Column 组装List 负责高性能列表渲染——虚拟滚动机制确保即使是上万条数据也不卡顿Navigation 负责页面导航管理——标题栏、返回按钮、页面切换动画一站式解决本文以一份完整的 ArkTS 代码项目为载体从 数据组织、状态管理、布局编排、导航控制 四个维度深入解析这一协作模式。项目本身也是一个「自指」的知识点集合——8 个列表条目本身就是 8 篇 ArkUI 核心知识点的介绍点击后可查看详细说明。无论你正在开发第一个鸿蒙应用还是在寻找更优雅的页面组织方式本文都将提供从理论到实践的全面参考。三大核心组件概述2.1 Column —— 弹性列布局Column 是 ArkUI 中最基础、最常用的布局容器。它的核心语义很简单子组件从上到下依次排列。Column├── 子组件 A ← top├── 子组件 B├── 子组件 C└── 子组件 D ← bottom但 Column 的强大之处在于它丰富的对齐和空间分配能力属性 作用 常用值justifyContent(FlexAlign) 主轴垂直方向对齐 Start(默认)、Center、End、SpaceBetween、SpaceAroundalignItems(HorizontalAlign) 交叉轴水平方向对齐 Start、Center(默认)、End、StretchlayoutWeight(number) 子组件在主轴上的权重分配 正数比例决定剩余空间的分配比例width(‘100%’) 宽度设置 百分比、vp 数值、LengthModepadding() / margin() 内边距 / 外边距 四边统一或分别指定在本项目中的角色 Column 是页面结构的骨架——它把标题区、搜索栏、列表区、底部提示垂直组合在一起每一部分本身又可能是 Column 或 Row 的嵌套。2.2 List —— 虚拟滚动列表List 是 ArkUI 专门为 长列表渲染 设计的高性能组件。它的最大特点是 虚拟滚动Virtual Scrolling只渲染当前可见区域内的 ListItem回收复用离屏的 ListItem预缓存前后若干项通过 cachedCount 控制屏幕可见区域┌──────────────────────┐│ ListItem A (可见) │ ← 渲染│ ListItem B (可见) │ ← 渲染│ ListItem C (可见) │ ← 渲染├──────────────────────┤│ ListItem D (离屏) │ ← 回收不复存在│ ListItem E (离屏) │ ← 回收│ ListItem F (离屏) │ ← 回收│ … (还有 9994 项) │ ← 从未存在└──────────────────────┘核心属性属性 作用 本项目的取值space(number) 列表项间距 8 vplistDirection(Axis) 列表方向 Axis.VerticalscrollBar(BarState) 滚动条策略 BarState.Auto自动显示/隐藏cachedCount(number) 预缓存项数 3divider(DividerStyle) 分割线样式 未使用通过 space 控制间距重要限制 List 的直接子组件只能是 ListItem、ListItemGroup 或 Section。任何其他组件如 Row、Column、NavRouter都不能直接放在 List 下面。2.3 Navigation —— 页面导航容器Navigation 是 ArkUI 为 多页面应用 设计的导航容器。它自动管理标题栏显示当前页面标题返回按钮可在详情页自动显示首页自动隐藏页面切换动画默认提供堆栈式 Push/Pop 动画标题模式支持 Mini紧凑和 Full标准两种Navigation 容器结构┌─────────────────────────┐│ ← 返回 标题文字 │ ← 自动管理的标题栏├─────────────────────────┤│ ││ 页面内容根据状态切换 ││ │└─────────────────────────┘本项目使用的属性Navigation().title(‘ArkTS 布局导航’).titleMode(NavigationTitleMode.Mini).hideBackButton(this.currentDetail null).hideToolBar(true).mode(NavigationMode.Stack)3. 列表—导航协作模式的设计思想3.1 为什么需要协作布局如果只用单一组件实现「列表 详情」会面临以下问题单一组件方案 问题只用 Column 长列表会渲染全部子组件 → 性能差无导航管理只用 List 只能渲染列表不能自主实现页面级切换只用 Navigation 没有内置的列表渲染能力需要额外组合协作布局的优势Column 负责垂直拼装 → 页面各区域的布局List 负责高效渲染 → 列表数据的虚拟滚动Navigation 负责页面管理 → 标题栏 返回按钮 页面切换三者各司其职组合起来就构成了一个完整的「列表浏览 → 详情查看」功能单元。3.2 数据驱动 vs DOM 操作在传统的命令式 UI 开发中开发者需要手动操作 DOM// 传统方式伪代码const list document.querySelector(‘#list’);list.innerHTML items.map(item li${item.title}/li);list.addEventListener(‘click’, (e) {const detail document.querySelector(‘#detail’);detail.innerHTML h1${e.target.title}/h1p${e.target.content}/p;detail.style.display ‘block’;});而在 ArkTS 的声明式 UI 中// 声明式方式build() {List() {ForEach(this.listData, (item) {ListItem() {Text(item.title)}.onClick(() { this.currentDetail item; });});}// 当 currentDetail 变化时UI 自动切换}核心区别 开发者只描述数据与 UI 的映射关系框架自动处理渲染和更新。3.3 状态驱动的页面切换本项目的页面切换完全由 State currentDetail 这一个状态变量驱动currentDetail null → 渲染列表首页currentDetail item → 渲染 item 的详情页currentDetail null (返回) → 重新渲染列表首页状态转换图点击列表项┌─────────────────────────────────┐│ │▼ │┌──────────┐ ┌──────────────┐│ 列表首页 │ │ 详情页 ││ current │── 点击条目 ──→│ current ││ Detail │ │ Detail ││ null │←── 返回 ────│ item │└──────────┘ └──────────────┘这种模式的好处单一数据源页面状态完全由 currentDetail 表达没有冗余状态可预测给定 currentDetail 的值UI 是确定的可回溯返回首页只需将 currentDetail 置 null易于调试在 DevEco Studio 中直接查看 State 的值即可了解当前页面状态4. 项目搭建与配置4.1 工程结构总览Demo06302/├── build-profile.json5 ← targetSdk6.1.1.24 (API 12)├── AppScope/│ └── app.json5 ← bundleName: com.example.demo0630└── entry/├── build-profile.json5 ← apiType: stageMode├── src/│ └── main/│ ├── module.json5 ← 注册 EntryAbility 页面路由│ ├── resources/ ← element / media / profile│ └── ets/│ ├── entryability/│ │ └── EntryAbility.ets ← 加载 pages/Index│ └── pages/│ └── Index.ets ← 核心实现 (459行)└── oh-package.json54.2 主题色系统设计本项目采用 Indigo靛蓝 作为主色调营造沉稳、专业、学习的氛围用途 色值 色名 应用位置主标题 #1A237E Indigo 900 页面大标题、详情页标题次标题 #283593 Indigo 800 详情区子标题强调色 #5C6BC0 Indigo 400 搜索按钮、返回按钮辅助色 #9FA8DA Indigo 200 说明文字、底部状态标题背景 #E8EAF6 Indigo 50 标题区背景色列表项 #FFFFFF 纯白 ListItem 背景页面底 #F5F5F5 Grey 100 整体页面背景警告色 #FFF8E1 Amber 50 原理说明卡片背景警告文字 #E65100 Deep Orange 900 原理说明文字颜色色彩选择背后的考量蓝色系给人冷静、专注的感觉适合学习场景高对比度标题 900 vs 背景 50确保信息层次清晰白色列表项在浅灰背景上形成卡片效果视觉分区明显橙色提示区与蓝色主调形成互补色对比吸引注意力4.3 数据类型定义interface ListItemData {id: number; // 唯一标识title: string; // 主标题列表首页显示subtitle: string; // 副标题列表首页显示icon: string; // 图标emoji装饰性标识detailTitle: string; // 详情页标题detailContent: string; // 详情页内容支持 \n 换行}数据结构设计要点字段 为什么需要 在何处使用id 作为唯一标识未来可用于搜索过滤 详情页元信息title 列表项的主标题用户最关注的信息 列表首页的 ListItemsubtitle 补充说明降低阅读决策成本 列表首页的 ListItemicon 视觉装饰增强辨识度 列表首页的 ListItem 详情页头部detailTitle 详情页标题与列表标题可不同 Navigation 标题栏 详情页头部detailContent 核心内容富文本格式 详情页内容区将 title 和 detailTitle 分开设计的理由是列表标题通常需要简短易扫描如List 虚拟滚动而详情页标题可以更完整如List 虚拟滚动列表两者的信息密度需求不同。Index.ets 完整代码逐段解析5.1 数据组织列表数据源设计private readonly listData: ListItemData[] [{id: 1,title: ‘鸿蒙原生开发’,subtitle: ‘ArkTS 语言特性与声明式 UI’,icon: ‘’,detailTitle: ‘鸿蒙原生开发概述’,detailContent: ‘ArkTS 是鸿蒙原生应用的首选开发语言…’},// … 共 8 条];设计意图 8 条知识点本身就是一篇微型 ArkUI 教程。用户在使用应用的过程中不仅看到了布局效果还能学到以下知识点ID 知识点 学习要点1 鸿蒙原生开发 ArkTS 核心特性概览2 Column 布局 对齐、权重、嵌套3 List 虚拟滚动 缓存、方向、虚拟化原理4 Navigation 导航 页面栈、标题栏、返回控制5 Scroll 滚动容器 与 List 的对比6 State 状态管理 响应式编程核心7 ForEach 循环渲染 声明式列表映射8 Row 水平布局 水平排列与 Flex 对齐这种应用即教程的设计让示例代码本身就具有教学价值。5.2 状态体系State currentDetail 驱动页面切换State currentDetail: ListItemData | null null;State searchValue: string ‘’;两个 State 变量是整个应用的大脑变量 类型 初始值 作用currentDetailListItemData nullnullsearchValue string ‘’ 演示交互存储搜索输入currentDetail 的三态逻辑// build() 中的条件判断if (this.currentDetail null) {// → 渲染列表首页} else {// → 渲染选中条目的详情页}// 导航栏返回按钮联动.hideBackButton(this.currentDetail null)// → 首页隐藏详情页显示这种模式是 ArkTS 中实现页面切换的标准方式——不需要复杂的路由配置一个 State 变量 一个 if/else 足矣。5.3 列表页首页的 Column 分层结构列表页的布局完全依靠 Column 的嵌套实现Column (page-root, height100%, padding8)│├── Column (标题区, backgroundColor#E8EAF6)│ ├── Text(“ ArkTS 布局导航”)│ ├── Text(“Column List Navigation 协作布局”)│ └── Text(“点击列表项查看详情…”)│├── Row (搜索/操作栏, width95%)│ ├── TextInput(placeholder“ 搜索…”)│ └── Button(“⇅ 排序”)│├── Row (列表计数, “ 共 8 个知识点”)│├── List (虚拟滚动列表, layoutWeight1 ← 占满剩余空间)│ └── ForEach × 8 条│ └── ListItem → Row(图标 标题Column 箭头)│└── Row (底部提示, “ 点击任意条目查看详情 →”)关键点 layoutWeight(1) 让 List 占满 Column 中标题区、搜索栏、计数行和底部提示之外的所有剩余空间确保列表有最大化的展示区域。5.4 标题区域——品牌呈现Column() {Text(‘ ArkTS 布局导航’).fontSize(22).fontWeight(FontWeight.Bold).fontColor(‘#1A237E’).margin({ bottom: 4 });Text(‘Column List Navigation 协作布局’).fontSize(13).fontColor(‘#5C6BC0’).margin({ bottom: 6 });Text(‘点击列表项查看详情Navigation 自动管理页面切换’).fontSize(11).fontColor(‘#9FA8DA’).textAlign(TextAlign.Center);}.width(‘100%’).padding({ top: 16, bottom: 12 }).backgroundColor(‘#E8EAF6’).borderRadius({ bottomLeft: 16, bottomRight: 16 });设计细节三级标题体系主标题22fp→ 副标题13fp→ 说明11fp逐级缩小字号仅底部圆角bottomLeft/bottomRight而非全部圆角形成「顶部悬挂」效果背景色 #E8EAF6 与页面主体 #F5F5F5 形成微妙色差区分区域5.5 搜索操作栏——Row 水平布局Row() {TextInput({ placeholder: ‘ 搜索布局知识…’ }).layoutWeight(1).height(36).fontSize(13).backgroundColor(‘#FFFFFF’).borderRadius(18).padding({ left: 16, right: 16 }).onChange((val: string) {this.searchValue val;});Button() {Text(‘⇅ 排序’).fontSize(12).fontColor(‘#FFFFFF’);}.type(ButtonType.Capsule).height(36).backgroundColor(‘#5C6BC0’).margin({ left: 8 });}.width(‘95%’).padding({ top: 8, bottom: 8 }).alignItems(VerticalAlign.Center);布局要点layoutWeight(1) 让 TextInput 占据按钮之外的全部水平空间输入框使用 borderRadius(18) 实现圆角效果高度 36一半即为 18形成完美的胶囊形按钮使用 ButtonType.Capsule 同样保持胶囊形视觉风格统一alignItems(VerticalAlign.Center) 确保两个子组件垂直居中5.6 List 虚拟滚动列表——核心渲染区域List({ space: 8 }) {ForEach(this.listData, (item: ListItemData) {ListItem() {// … 列表项内容}.width(‘100%’).backgroundColor(‘#FFFFFF’).borderRadius(12).onClick(() {this.onItemClick(item);});});}.width(‘100%’).layoutWeight(1).listDirection(Axis.Vertical).scrollBar(BarState.Auto).cachedCount(3).margin({ top: 4 });参数解析参数 值 作用space: 8 8vp 列表项之间的垂直间距layoutWeight(1) 1 占据 Column 中剩余的所有空间listDirection(Axis.Vertical) 纵向 标准的从上到下列表scrollBar(BarState.Auto) 自动 滚动时显示滚动条静止时隐藏cachedCount(3) 3 在可见区域外上下各保留 3 个渲染的 Item5.7 ListItem 内容模板——图标 标题 箭头ListItem() {Row() {// 1. 图标左Text(item.icon).fontSize(28).margin({ right: 12 });// 2. 标题 副标题中 Column() { Text(item.title) .fontSize(16).fontWeight(FontWeight.Medium).fontColor(#37474F); Text(item.subtitle) .fontSize(12).fontColor(#90A4AE).margin({ top: 2 }); } .layoutWeight(1) .alignItems(HorizontalAlign.Start); // 3. 右箭头指示器右 Text(›).fontSize(22).fontColor(#B0BEC5);}.width(‘100%’).padding(12).alignItems(VerticalAlign.Center);}这是移动端最经典的「左图标 中标题 右箭头」模式在各种应用中广泛使用。布局分析┌──────────────────────────────────────────┐│ ┌────┐ ┌──────────────────┐ ┌────────┐ ││ │ │ │ 鸿蒙原生开发 │ │ › │ ││ │ │ │ ArkTS 语言特性… │ │ │ ││ └────┘ └──────────────────┘ └────────┘ ││ 图标 标题 副标题 右箭头 ││ (28fp) (layoutWeight1) (22fp) │└──────────────────────────────────────────┘图标列固定宽度由内容撑开中间列使用 layoutWeight(1) 占据所有弹性空间右箭头列固定宽度这种模式保证了在任意屏幕宽度下标题都能获得最大展示空间。5.8 详情页的 Scroll Column 双布局组合Column() {Scroll() {Column() {// 标题区// 内容区// 按钮区// 原理说明区}.width(‘100%’).padding(12);}.width(‘100%’).layoutWeight(1);}为什么详情页不使用 List 而使用 Scroll Column对比维度 Scroll Column List子组件类型 任意组件 仅限 ListItem/ListItemGroup/Section渲染策略 全部渲染 虚拟滚动按需渲染适用场景 内容形式多样的页面 大量同构列表项布局灵活性 极高可嵌套各种组件 低结构受限详情页包含标题区Column、内容卡片Column、按钮行Row、说明卡片Column等形式各异的内容区块因此 Scroll Column 是比 List 更合适的选择。5.9 详情内容区的多层次 Column 嵌套详情页内容区展示了 Column 的 多层嵌套 能力Scroll└── Column (root, padding12)│├── Column (标题区, 圆角16)│ ├── Text(图标, fontSize48)│ ├── Text(detailTitle, fontSize22, Bold)│ └── Text(元信息行, fontSize11)│├── Column (内容卡片, 白色背景, 圆角12)│ ├── Text(“ 详细介绍”, fontSize16)│ └── Text(detailContent, fontSize14)│├── Row (按钮组)│ ├── Button(“← 返回列表”, 靛蓝)│ └── Button(“ 收藏”, 浅靛蓝)│└── Column (原理说明, 橙色背景, 圆角12)├── Text(“ Column List Navigation 协作原理”)└── Text(“• Column…\n• List…\n• Navigation…”)每一层 Column 都独立设置 width(‘100%’)确保在水平方向撑满。5.10 Navigation 容器属性详解Navigation().title(‘ArkTS 布局导航’).titleMode(NavigationTitleMode.Mini).hideBackButton(this.currentDetail null).hideToolBar(true).mode(NavigationMode.Stack)属性 值 效果title(‘ArkTS 布局导航’) 字符串 设置导航栏标题titleMode(Mini) 迷你模式 标题栏占用高度更小留给内容更多空间hideBackButton(动态) 布尔值 currentDetail null 时隐藏否则显示hideToolBar(true) 永久隐藏 不显示底部工具栏mode(Stack) 堆栈模式 页面以堆栈方式切换Push/PophideBackButton 的动态联动.hideBackButton(this.currentDetail null)首页currentDetail null → hideBackButton(true) → 隐藏返回按钮详情页currentDetail ! null → hideBackButton(false) → 显示返回按钮不需要手动监听返回按钮的点击事件——Navigation 在用户点击返回按钮时会触发一个系统级的返回动作。但由于本项目的页面切换是通过 State 实现的返回按钮的点击行为需要额外处理。在 HarmonyOS NEXT 中Navigation 的返回按钮点击默认会触发页面栈的 pop 操作。对于使用 State 条件渲染实现的页面切换需要通过 onBackClick 回调监听.onBackClick(() { this.onBackToList(); return false; })。不过在本版本的 API 中由于我们使用了 if/else 条件渲染而非真正的 NavDestination 页面栈返回按钮的显示/隐藏联动本身已经提供了足够的交互提示。Navigation 导航模式深度解析6.1 Navigation 工作原理Navigation 在底层维护了一个 页面栈Page Stack操作用户点击列表项→ 推入详情页Push┌──────┐ │ 详情页 │ ← Top ├──────┤ │ 首页 │ └──────┘操作用户点击返回→ 弹出详情页Pop┌──────┐ │ 首页 │ ← Top └──────┘在条件渲染模式下本项目使用虽然没有真正的页面栈但 Navigation 仍然维持了标题栏和返回按钮的一致性。6.2 标题模式Mini vs FullNavigation 提供两种标题模式模式 标题栏高度 适用场景 本项目选择原因NavigationTitleMode.Mini 约 40vp 内容密集型页面 列表内容更重要NavigationTitleMode.Full 约 80vp 品牌展示型页面 适合需要大标题的应用Mini 模式在移动设备上能多展示 1~2 个列表项对于列表浏览型应用来说收益明显。6.3 返回按钮的联动控制hideBackButton 的巧妙之处在于它绑定了一个动态的 State 表达式.hideBackButton(this.currentDetail null)当 State 变化时Navigation 自动重新计算属性值无需任何额外代码。这种响应式属性绑定是 ArkUI 声明式 UI 的核心优势。6.4 NavRouter 与条件渲染的比较在开发初期我尝试使用 NavRouter 组件来实现导航但遇到了两个问题问题 说明List 子组件限制 List 的直接子组件只能是 ListItem而 NavRouter 包裹 ListItem 违反了约束NavRouter 废弃 在 API 12 中NavRouter 已被标记废弃迁移方案 使用 State 条件渲染代替 NavRouter。NavRouter 方案旧 State 方案新Navigation() Navigation()├── List() ├── if (state null)│ └── NavRouter() │ → 列表首页│ └── ListItem() └── else└── NavDestination() → 详情页新方案的优势更简单不需要学习和配置路由组件更灵活页面内容完全由代码控制更高效避免了不必要的组件层级7. List 虚拟滚动机制详解7.1 虚拟滚动的核心原理传统列表如 Scroll ForEach会渲染所有列表项的 UI 组件Scroll 传统模式渲染全部┌────────────┐│ Item 1 │ ← 渲染│ Item 2 │ ← 渲染│ Item 3 │ ← 渲染│ … │ ← 渲染全部 10000 项│ Item 9999 │ ← 渲染│ Item 10000 │ ← 渲染└────────────┘→ 内存占用10000 个组件的开销→ 性能大量 DOM 节点滑动卡顿而 List 的虚拟滚动模式只渲染可视区域附近的几个项List 虚拟滚动按需渲染┌────────────┐│ Item 1 │ ← 回收不可见│ Item 2 │ ← 缓存 (cachedCount)│────────────││ Item 3 │ ← 渲染可见│ Item 4 │ ← 渲染可见│ Item 5 │ ← 渲染可见│────────────││ Item 6 │ ← 缓存 (cachedCount)│ Item 7 │ ← 未创建│ … │ ← 未创建└────────────┘→ 内存占用7 个组件3 可见 22 缓存7.2 缓存策略cachedCountcachedCount 控制可见区域之外预渲染的列表项数量cachedCount 值 总渲染项数 滑动体验 内存占用0 3 项仅可见 快速滑动可能出现白屏 最低3 9 项3可见3上3下 滑动流畅 低10 23 项 极速滑动也无延迟 中等100 203 项 无需更多缓存 较高本项目设置为 cachedCount(3)兼顾了流畅度和内存占用。7.3 性能对比List vs Scroll Column场景 List虚拟滚动 Scroll Column10 条数据 ✅ 优秀 ✅ 优秀100 条数据 ✅ 优秀 ✅ 良好1000 条数据 ✅ 优秀 ❌ 明显卡顿10000 条数据 ✅ 流畅仅渲染~9项 ❌ 不可用混合内容布局 ❌ 受限只能 ListItem ✅ 完全自由黄金法则 列表项数量超过 50 条时优先选择 List50 条以下且内容形式多样时Scroll Column 更灵活。Column 布局深入实践8.1 Column 的嵌套策略在整个应用中Column 以 4 层嵌套组织页面Level 0: Navigation (根容器)Level 1: Column (页面根容器含 padding)Level 2: Column (标题区) / List (列表区) / Row (底部)Level 3: Column (详情内容卡片) / Row (列表项)Level 4: Column (标题文字组) / Row (按钮组)嵌套规则每层 Column 负责一个明确的视觉区块避免超过 5 层嵌套超出后代码可读性下降每个 Column 都设置 width(‘100%’)确保水平撑满8.2 layoutWeight 的空间分配layoutWeight 是 Column 和 Row 中最强大的空间分配工具Column() {// 标题区 - 不设 layoutWeight → 由内容撑开固定高度Text(‘标题’).fontSize(22);// 列表区 - layoutWeight(1) → 占满所有剩余空间List() { }.layoutWeight(1);// 底部提示 - 不设 layoutWeight → 由内容撑开固定高度Text(‘提示’).fontSize(11);}.height(‘100%’)空间分配计算总高度 父容器 height(100%) 标题区高度 列表区高度 底部提示高度 内容撑开高度 layoutWeight(1)·剩余空间 内容撑开高度布局效果标题和底部按内容高度固定列表区占满中间所有空间。不论屏幕大小如何变化这种「头尾固定、中间自适应」的布局模式都稳定可靠。8.3 Column Row 的组合模式Column 和 Row 在 ArkUI 中的关系类似于 Flexbox 中的 flex-direction: column 和 flex-direction: row。项目中最常见的组合模式模式 代码结构 效果列表条目 Row[图标 Column(标题副标题) 箭头] 左中右经典模式搜索栏 Row[TextInput(layoutWeight1) Button] 输入框按钮组合按钮组 Row[Button Button(marginLeft)] 水平排列的操作按钮计数行 Row[Text] 单行信息展示9. 编译与调试经验9.1 List 子组件限制错误信息The component ‘List’ can only have the child component ‘ListItem,Section,ListItemGroup’.The ‘ListItem’ component can only be nested in the ‘List,ListItemGroup’ parent component.原因 最初的结构是List() {NavRouter() { // ← List 无法接受 NavRouter 作为子组件ListItem() { } // ← ListItem 不在 List 的直接子节点中}}解决方案 承认 List 的结构约束使用 State 条件渲染替代 NavRouter 做页面切换。List() {ListItem() { } // ✅ 唯一允许的直接子组件}启示 ArkTS 的组件约束是编译时检查的违反就会报错。不要试图绕过这些约束而是理解它们背后的设计意图——List 的子组件限制确保了虚拟滚动机制的正确工作。9.2 NavRouter 废弃的迁移路线警告信息WARN: ‘NavRouter’ has been deprecated.NavRouter 在 API 12 中被标记废弃建议的替代方案是旧方案 新方案NavRouter NavDestination Navigation 条件渲染if/else路由声明式导航 状态驱动导航隐式耦合 显式数据流9.3 NavigationTitleMode 类型约束Navigation 的 titleMode 属性接受枚举值而非字符串// ✅ 正确.titleMode(NavigationTitleMode.Mini)// ❌ 错误.titleMode(‘Mini’)同样NavigationMode.Stack 也不能写成 ‘Stack’。这是 ArkTS 中常见的枚举使用方式。效果展示与交互流程10.1 列表首页布局┌──────────────────────────────────────┐│ ← ArkTS 布局导航 │ ← Navigation 标题栏Mini 模式├──────────────────────────────────────┤│ ArkTS 布局导航 ││ Column List Navigation 协作布局 │ ← 标题区 (Indigo 50)│ 点击列表项查看详情… │├──────────────────────────────────────┤│ ┌─ 搜索布局知识… ──┬─ ⇅ 排序 ─┐│ ← 搜索操作栏│ └────────────────────────┴─────────┘││ 共 8 个知识点 ││ ┌──────────────────────────────┐ ││ │ 鸿蒙原生开发 › │ │ ← ListItem × 8│ │ ArkTS 语言特性与声明式 UI │ │ (白色卡片, 圆角12)│ ├──────────────────────────────┤ ││ │ Column 布局 › │ ││ │ 弹性列布局及其应用场景 │ ││ ├──────────────────────────────┤ ││ │ List 虚拟滚动 › │ ││ │ 高性能长列表渲染机制 │ ││ ├──────────────────────────────┤ ││ │ Navigation 导航 › │ ││ │ 页面容器与状态驱动的切换 │ ││ └──────────────────────────────┘ ││ 点击任意条目查看详情 → │└──────────────────────────────────────┘10.2 详情页布局┌──────────────────────────────────────┐│ ← ArkTS 布局导航 │ ← 显示返回按钮├──────────────────────────────────────┤│ ││ ││ 鸿蒙原生开发概述 │ ← 详情标题区│ ID: 1 | 导航层级: 1 | ArkTS 语言… ││ ││ ┌─ 详细介绍 ─────────────────┐ ││ │ ArkTS 是鸿蒙原生应用的首选… │ │ ← 内容卡片│ │ │ ││ │ 核心特性 │ ││ │ • Entry/Component… │ ││ │ • State 驱动 UI… │ ││ │ • 链式属性调用… │ ││ └────────────────────────────────┘ ││ ││ [← 返回列表] [ 收藏] │ ← 操作按钮│ ││ ┌─ ColumnListNavigation… ─┐ ││ │ • Column垂直组合… │ │ ← 原理说明│ │ • List虚拟滚动… │ ││ │ • Navigation管理页面切换… │ ││ └────────────────────────────────┘ │└──────────────────────────────────────┘10.3 典型交互流程启动应用 → 看到列表首页Navigation 标题栏显示ArkTS 布局导航滑动列表 → List 虚拟滚动流畅工作所有 ListItem 有白色卡片背景和圆角点击List 虚拟滚动条目 → currentDetail 赋值为该条目数据 → 切换到详情页详情页展示 → 顶部大图标 标题中间详细介绍内容底部有原理说明点击「← 返回列表」按钮 → currentDetail 置 null → 回到列表页再次进入另一个条目 → 看到完全不同的详情内容在搜索框中输入文字 → searchValue 状态更新虽未实现实际搜索过滤但数据流已就位性能分析与最佳实践11.1 列表渲染性能以 8 条数据为例List 的渲染性能分析指标 值数据总量 8 条可见区域项数 约 4 条渲染项数含缓存 约 7 条内存占用 ≈ 7 × (ListItem 子组件)滑动帧率 60fps流畅对于 8 条数据List 的优势不明显——Scroll Column 也能流畅渲染。但 List 的优势在于当数据扩展到成百上千条时性能表现不变。11.2 最佳实践清单实践 说明1 List 子组件只能是 ListItem 不支持 NavRouter、Column 等直接作为 List 的子组件2 使用 State 驱动页面切换 比 NavRouter 更简洁、灵活、无废弃风险3 Column 每层设置 width(‘100%’) 防止内容宽度异常4 详情页使用 Scroll Column 比 List 更适合内容形式多样的页面5 数据模型分离显示字段 title 和 detailTitle 分开适配不同场景6 layoutWeight(1) 用于弹性撑满 让列表区自适应剩余空间7 Navigation 与 State 联动 hideBackButton 绑定状态表达式8 ForEach 配合 List 使用 数据驱动列表渲染View 与 Data 解耦12. 扩展方向12.1 搜索过滤功能基于现有的 searchValue 状态可以轻松实现实时搜索过滤get filteredList(): ListItemData[] {const keyword this.searchValue.trim().toLowerCase();if (keyword ‘’) return this.listData;return this.listData.filter(item item.title.toLowerCase().includes(keyword) ||item.subtitle.toLowerCase().includes(keyword));}然后在 ForEach 中替换数据源ForEach(this.filteredList, (item: ListItemData) { … });12.2 分组列表——Section 组件当列表数据需要分组时可以使用 ListItemGroup 或 Section 组件List() {Section({ header: ‘基础布局’ }) {ForEach(basicLayoutItems, (item) { ListItem() { … } });}Section({ header: ‘导航路由’ }) {ForEach(navigationItems, (item) { ListItem() { … } });}}12.3 路由传参与多级导航对于更复杂的导航需求可以扩展 currentDetail 为导航栈State navStack: ListItemData[] [];// 推入onPush(item: ListItemData): void {this.navStack.push(item);}// 弹出onPop(): void {this.navStack.pop();}// 当前页面get currentPage(): ListItemData | null {return this.navStack.length 0? this.navStack[this.navStack.length - 1]: null;}这种手动的导航栈可以实现任意深度的页面跳转。总结本文通过一个完整的 HarmonyOS NEXT ArkTS 项目深入解析了 Column List Navigation 协作布局 的实现原理和工程实践。知识点 核心内容Column 垂直布局容器嵌套组合标题、搜索栏、列表、底部提示List 虚拟滚动列表space(8) 间距cachedCount(3) 缓存Navigation 导航容器titleMode(Mini) 紧凑标题State 联动返回按钮State 驱动 currentDetail 控制列表/详情切换单一数据源ForEach 数据驱动渲染8 条知识条目循环生成Row Column 「左图标 中标题 右箭头」经典列表项布局模式Scroll Column 详情页的富内容组合适合形式多样的页面展示Column、List、Navigation 三者协作的核心理念可以概括为一句话Column 搭骨架List 管内容Navigation 控流程。在实际的鸿蒙原生应用开发中这一协作模式将出现在绝大多数页面中。无论是新闻列表、商品目录、好友通讯录还是设置页面都可以复用本文介绍的架构思路。希望本文能帮助你在鸿蒙原生应用开发的道路上更进一步。如果你对布局和导航有更多的创意欢迎在实际项目中大胆探索。参考资料HarmonyOS NEXT 开发者文档 — ArkUI 组件参考Column、List、NavigationArkTS 装饰器参考 — State / Prop / Link / WatchMaterial Design 3 — 列表与导航模式声明式 UI 编程范式 — 状态驱动视图更新虚拟滚动算法原理 — 计算机图形学中的视锥体裁剪