系列:《Web 到 HarmonyOS》· 列表专题
适合人群:会 Vuev-for/:key/ 虚拟列表,准备写流畅的鸿蒙列表
写在前面
Web 里列表常常是:ul + v-for,卡了再上虚拟列表库;下拉刷新、触底加载靠业务自己拼。
鸿蒙把「容器结构 / 循环渲染 / 虚拟化与回收 / 刷新加载」拆成几层能力。前端心智可以这样对齐:
| 你想做的事 | 鸿蒙 | 近似 Web |
|---|---|---|
| 可滚动列表容器 | List | 带滚动的列表容器,不是随便套 div |
| 分组 | ListItemGroup | 通讯录按字母、商品按分类 |
| 一行数据 | ListItem | 一条 li / 一张卡片根节点 |
| 少~中量循环 | ForEach | v-for |
| 海量 + 更彻底回收 | LazyForEach | 虚拟列表 + 节点回收 |
| 复杂/条件行模板 | @Builder | 抽成子组件或 v-if 分支模板 |
| 下拉刷新 | refreshable | 手势库 / 组件库的 pull-refresh |
| 触底加载 | onReachEnd | IntersectionObserver / 滚动到底 |
选型一句话: 设置页、几十条以内 → List + ForEach;新闻流、商品流、可能上千上万 → 优先想 LazyForEach + 分页,并配合轻量 item、@Reusable、图片懒加载。
一、List 三层结构(先别急着写 v-for)
ArkUI 里列表不是「Column 里堆一堆 Text」,而是固定三层:
List ← 根容器:方向、列数、滚动、分隔线
├─ ListItemGroup? ← 可选分组
└─ ListItem ← 每一行(直接子节点必须是 ListItem 或 Group)
└─ 你的内容 / 自定义组件
| 层级 | 管什么 | Web 对照 |
|---|---|---|
List | 竖/横滚、多列 lanes、分隔线、刷新/触底 | 列表壳子 + 滚动策略 |
ListItemGroup | 分组标题与分段 | sticky section / 分组 header |
ListItem | 一条记录的根 | 单行卡片根节点 |
主轴未设死尺寸时,List 会自适应:子项总高度小于父级则跟着子项走;超出则占满父级并出现滚动——和「外层定高、内层溢出滚动」的 Web 习惯类似,但规则写在组件自身上。
二、数据绑定:ForEach 与 @Builder
2.1 ForEach ≈ v-for(中小数据首选)
社区实践里,数据量不大(常见说法:千条以内量级) 用 ForEach 即可,写法最接近 Vue:
@Entry
@Component
struct NewsList {
@State newsData: Array<NewsItemModel> = []
build() {
List() {
ForEach(this.newsData, (news: NewsItemModel) => {
ListItem() {
NewsItem({ news: news })
}
}, (news: NewsItemModel) => news.id.toString()) // Key,必写稳
}
}
}
@Component
struct NewsItem {
@Prop news: NewsItemModel = new NewsItemModel()
build() {
Row() {
Text(this.news.title).fontSize(16)
}
.padding(10)
}
}
| Vue | ArkUI |
|---|---|
v-for="news in newsData" | ForEach(this.newsData, ...) |
:key="news.id" | 第三个参数 news.id.toString() |
| 子组件 props | @Prop / 自定义组件入参 |
| 省略 key / 用 index | 排序、插入时错位与多余重建 |
补充:ForEach 数据源可以是数组,也可以是 Set / Map 等可迭代对象(业务里仍以数组最常见)。
2.2 Key 三条硬规则(和 Vue 同一铁律,执行更严)
- 唯一:整表生命周期内每条一个不同 key。
- 稳定:优先数据库主键、业务 ID、UUID;不要用数组 index,也不要用每次渲染新算的随机数。
- 简单:字符串或数字即可,别拿复杂对象当 key。
Key 错了:状态串行、滚动复用错乱、性能掉——ArkUI 靠 key 认「是不是同一行」。
// ❌
(item, index) => index.toString()
// ✅
(item) => item.id.toString()
2.3 @Builder:条件行 / 复杂行模板
Web 里你会把「重要新闻红字、普通黑字」拆成小组件或 v-if。鸿蒙可用 @Builder 提高可读性与复用:
@Builder
function buildNewsItem(news: NewsItemModel) {
if (news.type === 'important') {
ListItem() {
Text(news.title)
.fontColor(Color.Red)
.fontWeight(FontWeight.Bold)
}
} else {
ListItem() {
Text(news.title).fontColor(Color.Black)
}
}
}
List() {
ForEach(this.newsData, (news: NewsItemModel) => {
buildNewsItem(news)
}, (news: NewsItemModel) => news.id.toString())
}
行结构复杂、分支多时:优先「自定义组件 + @Prop」;分支样式简单时用 @Builder 就够。
三、性能:虚拟化、LazyForEach、分页与图片
数据一大,一次建满所有行会:首屏卡、内存高、滑动掉帧。按优先级处理。
3.1 List 自带虚拟化(ForEach 也不等于「浏览器里全量 DOM」)
API 9 起,List 对 ForEach 已有内置虚拟滚动思路(和「裸 Column + ForEach 全堆」不同):
| 阶段 | 行为(理解用) |
|---|---|
| 初始化 | 优先创建、布局可视区内的 ListItem |
| 空闲 | 预加载范围内的项再补布局 |
| 更远 | 更外围项更「轻」,内部子树不必全建满 |
所以:短~中列表 用 List + ForEach 往往已经比 Web 裸 v-for 省心。
但仍要注意:ForEach 模式下,滑出可视区的项通常不会像 LazyForEach 那样销毁回收,内存会随数据规模持续抬升。海量场景仍要升级策略。
(极特殊:行极高、自研滚动逻辑时,才考虑手动「占位总高 + 只渲染 visible 窗口」——多数业务用不到,优先官方 List / LazyForEach。)
3.2 LazyForEach:海量数据的彻底回收
万级以上、新闻/电商长列表,用 LazyForEach:
| ForEach(在 List 里) | LazyForEach | |
|---|---|---|
| 创建 | 可视 + 预加载等策略 | 按需迭代数据源 |
| 滑出预加载区 | 项多半仍占着 | 可销毁;带 @Reusable 的可进复用池 |
| 数据源 | @State 数组等 | 实现 IDataSource,改数据走 listener |
| 近似 Web | 加强版 v-for | 虚拟列表 + 回收 |
约束(踩坑高频):
- 懒加载预期落在
List/Grid/Swiper/WaterFlow/ListItemGroup等容器;嵌套同向滚动且未限高时,可能全量加载,懒加载失效。 - 一个容器里不要硬拼多个
LazyForEach,也不要和大量静态ListItem/ForEach混用。 - 每次迭代只出一个子组件根;key 同样要唯一稳定。
- 不要靠重赋值整个
dataSource指望刷新;用onDataAdd/onDataDelete/onDataChange/onDataReloaded。
最小数据源骨架:
class BasicDataSource implements IDataSource {
private list: NewsItemModel[] = []
private listeners: DataChangeListener[] = []
totalCount(): number {
return this.list.length
}
getData(index: number): NewsItemModel {
return this.list[index]
}
registerDataChangeListener(listener: DataChangeListener): void {
if (this.listeners.indexOf(listener) < 0) {
this.listeners.push(listener)
}
}
unregisterDataChangeListener(listener: DataChangeListener): void {
const pos = this.listeners.indexOf(listener)
if (pos >= 0) {
this.listeners.splice(pos, 1)
}
}
setData(data: NewsItemModel[]): void {
this.list = data
this.listeners.forEach((l: DataChangeListener) => l.onDataReloaded())
}
append(items: NewsItemModel[]): void {
const start = this.list.length
this.list = this.list.concat(items)
this.listeners.forEach((l: DataChangeListener) => {
// 按实际 API 选用批量增加或逐条 onDataAdd
l.onDataAdd(start)
})
}
}
List() {
LazyForEach(this.dataSource, (item: NewsItemModel) => {
ListItem() {
NewsItem({ news: item })
}
}, (item: NewsItemModel) => item.id.toString())
}
.width('100%')
.height('100%')
.cachedCount(4)
getData 保持轻量:滑动时会频繁调用,重计算 / 同步 IO 会直接变成掉帧。
3.3 cachedCount:预加载缓冲
可视区上下再缓存若干项,减轻「快速滑露白」。
| 建议 | 说明 |
|---|---|
| 约一屏条数的一半 | 官方常见量级 |
| 复杂卡片 3~5 | 实战折中 |
| 过大 | 首屏与内存变差 |
| 过小 | 快滑露白、掉帧 |
3.4 列表项与图片
- 轻量
ListItem:少深层嵌套、少在build里算重活。 - 图片:
Image使用懒加载(如.lazyLoad(true)),非可视区不急着解码;再配合合适尺寸、格式与缓存。 @Reusable:复杂卡片进出屏时复用节点,在aboutToReuse换数据;一行纯文字收益有限。- 状态下沉:选中、展开放在 item 自己的
@State,别让父组件一大坨@State改一行刷整表。 - 滚动中:少改全局状态,避免整树无效刷新。
3.5 分页:虚拟化管「怎么画」,分页管「怎么要数据」
Web 信息流 = 虚拟列表 + loadMore。鸿蒙同样:渲染层用 ForEach/LazyForEach,数据层用分页。
@Component
struct PaginatedList {
@State data: NewsItemModel[] = []
@State currentPage: number = 1
@State hasMore: boolean = true
@State isLoading: boolean = false
private async loadMore(): Promise<void> {
if (this.isLoading || !this.hasMore) {
return
}
this.isLoading = true
try {
const page = await fetchPage(this.currentPage)
if (page.length > 0) {
this.data = this.data.concat(page)
this.currentPage++
} else {
this.hasMore = false
}
} finally {
this.isLoading = false
}
}
build() {
List() {
ForEach(this.data, (item: NewsItemModel) => {
ListItem() {
NewsItem({ news: item })
}
}, (item: NewsItemModel) => item.id.toString())
}
.onReachEnd(() => {
this.loadMore()
})
}
}
isLoading 防连触;hasMore 防空刷;失败时记得回退页码(见下一节完整示例思路)。
四、标配交互:下拉刷新 + 上拉加载
移动端列表标配,鸿蒙用组件能力接,不必从零造手势。
4.1 下拉刷新:refreshable
刷新是替换数据,不是追加:
@State data: NewsItemModel[] = []
@State isRefreshing: boolean = false
private async handleRefresh(): Promise<void> {
this.isRefreshing = true
try {
this.data = await fetchLatestData()
} finally {
this.isRefreshing = false
}
}
List() {
ForEach(this.data, (item: NewsItemModel) => {
ListItem() { /* ... */ }
}, (item: NewsItemModel) => item.id.toString())
}
.refreshable({
onRefresh: () => {
this.handleRefresh()
}
// 视 API 版本还可配触发距离、阻力等
})
对照 Web:onRefresh ≈ pull-refresh 的回调;isRefreshing 控指示器显隐。
4.2 上拉加载:onReachEnd
触底 ≈ Web 的 infinite scroll。与刷新组合时记住:
| 操作 | 数据怎么变 | 页码 |
|---|---|---|
| 下拉刷新 | 整表替换 | 重置为 1,hasMore = true |
| 触底加载 | 尾部追加 | currentPage++,失败则回退 |
完整状态机建议:
isLoading:进行中拒绝重入。hasMore:本页不足pageSize则视为没有更多。- 底部 UI:
正在加载…/没有更多了。 - 失败:Toast + 页码回退,避免空洞页号。
五、布局与多设备
List()
.listDirection(Axis.Vertical) // 或 Horizontal
.lanes(2) // 多列(竖列表时常用来做双列卡片)
.alignListItem(ListItemAlign.Center)
.divider({
strokeWidth: 1,
color: '#F0F0F0',
startMargin: 20,
endMargin: 20
})
.scrollBar(BarState.Auto)
| 能力 | 用途 | Web 对照 |
|---|---|---|
listDirection | 横滑/竖滑 | flex-direction + 横向 scroll |
lanes | 多列 | CSS multi-column / 网格 |
divider | 分隔线 | border-bottom |
scrollBar | 滚动条显隐 | OS / CSS overlay scroll |
多设备:按屏宽动态 lanes(例如宽屏 2 列、窄屏 1 列),和 Web 响应式「断点改列数」同一思路。
六、常见坑与对策
| 现象 | 优先怀疑 | 对策 |
|---|---|---|
| 滚动时整表狂刷 | 状态粒度太大 | 状态下沉到 item;少动全局 @State |
| 图多就卡 | 同步解码大图 | lazyLoad、压尺寸、缓存 |
| 中间插入后错乱 | key 用了 index | 业务唯一 id |
| 懒加载没生效 | 同向嵌套 Scroll、List 未限高 | 单层 List;分组用 ListItemGroup |
| LazyForEach 不更新 | 重赋值了 dataSource | listener 通知增删改 |
| 触底连打接口 | 没闸门 | isLoading + hasMore |
| 复杂手势/动画卡 | 主线程过重 | 减树深;热路径考虑更轻绘制方式 |