HarmonyOS ArkTS 列表 List 详解
在应用开发里，“列表”几乎是最常见的 UI 结构之一。无论是联系人、消息流、商品列表、配置项、文件列表，它们的共同点是：数据项数量可能很多、需要支持滚动、每一行结构相似。ArkTS 提供了专门的
List容器来处理这种需求，让你不用手写滚动逻辑，也不需要自己管理内容溢出的布局。developer.huawei.com
一、List 是什么？
List 是一种专用容器组件，用于呈现一组结构相似的数据项目：
- 当项目数量多时自动提供滚动功能（通常是垂直方向）
- 内部会按照定义的方向自动排列各项
- 支持静态项 + 动态循环项结合使用
- 通常和
ListItem/ListItemGroup配合渲染每一行布局developer.huawei.com
用一句话描述它：
List 就像是 ArkTS 版本的“RecyclerView / LazyColumn”：把一堆同类型项目组织成一个“可滚动的列表容器”。developer.huawei.com
二、List 会做哪些工作？
在如果你用 Row/Column + Scroll 自己堆叠，这种页面可能正常滚动，但：
- 不会自动管理项目间距
- 不会自动控制布局方向约束
- 对动态数据的渲染不够“声明式”
而 List 做了这些：
自动滚动
当子组件总高度超过容器高度时，List 会自动启用滚动功能，无需你再手动加 Scroll。developer.huawei.com
自动排列
默认按主轴方向排列（默认是竖直），并在溢出时顺序滚动和重排。developer.huawei.com
场景通用
它适合各种列表场景，例如：
- 用户信息列表
- 文章流
- 订单/通知记录
- 图片 + 文本混合内容developer.huawei.com
三、List 的基本写法
最简单的列表就是把一堆 ListItem 放在一个 List 容器里：
List() {
ListItem() { Text("项目 A") }
ListItem() { Text("项目 B") }
ListItem() { Text("项目 C") }
}
上面这种写法很直白：
- List 是容器
- ListItem 是容器里的每一行内容
- 结构清晰、自动滚动显示developer.huawei.com
四、动态数据要配合 ForEach
现实中列表大多数数据来源于数据结构，比如数组。为了动态渲染 List 内容，官方推荐用 ForEach：
List() {
ForEach(this.items, (item) => {
ListItem() {
Row() {
Text(item.title)
Text(item.desc).fontSize(12)
}
}
})
}
这里的思路是：
this.items是一个数组，比如从状态或服务端拿到的数据ForEach按顺序把每个item渲染成一个ListItem- 渲染过程中你可以在每一项里做复杂布局（Row/Column/Flex 等）developer.huawei.com
为什么不用普通循环？ ForEach 是声明式渲染，它能和状态（@State）联动、在数据变化时自动刷新，无需你手动更新 UI。
五、List 常用属性
虽然官方 API 文档有完整说明，这里总结一些在开发中最常用的属性：
| 属性 | 作用 |
|---|---|
space | 子项目之间的主轴间距，越大列表显得越“松” |
initialIndex | 列表渲染时默认滚动到的起始项目索引 |
scroller | 可选绑定滚动控制器 |
listDirection | 主轴方向（默认竖直 Vertical，也可 Horizontal） |
例如：
List({ space: 8, initialIndex: 2 })
会让列表：
- 项之间有 8vp 间距
- 默认渲染到第 3 个项目位置CSDN博客
六、支持水平滚动或多列
虽然 List 默认是垂直滚动，但你也可以切换方向：
List()
.listDirection(Axis.Horizontal)
这样 List 会沿水平方向排列项目并横向滚动（常见于图片轮播集或横向卡片墙）。cnblogs.com
七、子组件必须是 ListItem / ListItemGroup
官方文档明确指出，List 里的子节点必须是 ListItem 或 ListItemGroup：
ListItem用于表示一个单独的列表项ListItemGroup则是一个分组结构（内部再包含 ListItem）
其它直接放的组件不会被识别为“列表项”，渲染和排列可能不会按预期工作。cnblogs.com
八、主/交叉轴与布局约束
List 会根据主轴方向自动排列：
- 主轴是 List 的滚动方向
- 交叉轴是与滚动方向垂直的方向
例如：
- 垂直列表：主轴上下排列；交叉轴左右排列
- 水平列表：主轴左右排列；交叉轴上下排列cnblogs.com
这意味着你可以控制垂直列表的列数或水平列表的行数，通过设置 lanes 属性（更高级用法）或用 Row/Flex 在 ListItem 内组织子结构。
九、性能优化技巧（实践经验）
列表内容一多，性能就很关键：
用 LazyForEach 替代 ForEach
在渲染极大量项目（比如千条以上）时，用 LazyForEach 可以只渲染当前视口附近的项，大幅提高流畅度。 （虽然官方基础文档未详细展开，这种模式在实践案例中很常见）CSDN博客
给 ListItem 设置 reuseId
为 ListItem 指定 reuseId 有助于框架复用组件，提高渲染和滚动性能。CSDN博客
十、开发中的注意事项
✔ 不要用 Column + Scroll 替代 List 显示大量数据 虽然看起来能滚动，但没有 List 那些自动排列、重用机制，性能和体验都弱。
✔ 结合状态管理更新列表 List 配合 @State 或 @Observable 数据变更能自动刷新 UI，无需手动局部更新。
✔ List 不自动分页 如果数据很多（比如无限滚动），建议自己做分页逻辑，再把新数据 push 到数组，然后 Let List 重新渲染。
✔ ListItem 内可以放任意布局 ListItem 内并不局限于 Text，你可以放 Row/Flex/Stack、图片、按钮等复杂 UI 结构。
总结
List是 ArkTS 的核心可滚动容器，用于渲染大量类似数据的场景。developer.huawei.com- 配合
ForEach或LazyForEach实现动态渲染。developer.huawei.com - 子级必须是 ListItem / ListItemGroup，否则不会按列表方式排列。cnblogs.com
- 支持竖直和水平方向，并有属性控制间距、起始位置等。CSDN博客
