HarmonyOSNext列表开发指南 ##Harmony OS Next ##Ark Ts ##教育 本文适用于教育科普行业进行学习，有错误之处请指出我会修改。
🎯 列表基础：你的数据管家 列表就像 智能收纳盒！内容太多时自动滚动，超适合展示： • 通讯录 👥 • 音乐歌单 🎵 • 购物车 🛒 • 新闻流 📰 ✨ 核心超能力
xxxxxxxxxx
List() {
// 三种姿势任你选 ↓↓↓
ListItem() // 单个元素
ForEach(...) // 循环渲染
ListItemGroup() // 分组显示
}
.scrollBar(BarState.Auto) // 自动滚动条
🧭 布局与约束：方向感很重要！ 📏 主轴 vs 交叉轴 列表类型 主轴方向 交叉轴方向 示例场景 垂直列表 垂直 ↓ 水平 → 朋友圈动态 水平列表 水平 → 垂直 ↓ 电影海报墙 ⚡ 黄金法则 主轴尺寸不够时自动撑开，超过父容器就截断！ 交叉轴默认占满父容器（想改？看这里 ↓↓↓）
🛠️ 开发四步曲 1️⃣ 设置滚动方向
xxxxxxxxxx
// 默认垂直滚动（不用写参数）
List() { ... }
// 水平滚动超简单！
List() { ... }
.listDirection(Axis.Horizontal) // ← 关键参数
2️⃣ 多列布局神器
xxxxxxxxxx
// 两列垂直列表
List() { ... }
.lanes(2) // 🎯 自适应列数
.alignListItem(ListItemAlign.Center) // 居中对齐
💡 超实用技巧
用 lanes: {minLength:200, maxLength:300} 自动适配不同屏幕！
平板秒变两列，手机单列显示~
🎮 动态数据绑定：告别重复代码！ 联系人列表实战
xxxxxxxxxx
// 数据类
class Contact {
key: string = util.generateRandomUUID(true);
name: string;
avatar: Resource; // 头像资源
}
// 列表组件
@Entry
@Component
struct ContactsList {
@State contacts: Contact[] = [
new Contact("小明", $r("app.media.avatar1")),
new Contact("小红", $r("app.media.avatar2"))
]
build() {
List() {
ForEach(this.contacts, (item) => {
ListItem() {
Row() {
Image(item.avatar) // 头像
.width(40).height(40).margin(10)
Text(item.name).fontSize(20) // 名字
}
}
})
}
}
}
💅 颜值即正义：样式美颜指南 1️⃣ 添加分隔线
xxxxxxxxxx
List() { ... }
.divider({
strokeWidth: 1, // 线宽
startMargin: 60, // 左边距
endMargin: 10, // 右边距
color: '#F0F0F0' // 颜色
})
2️⃣ 小红点标记
xxxxxxxxxx
ListItem() {
Badge({
count: 3,
position: BadgePosition.RightTop,
style: { badgeSize: 16, badgeColor: '#FF3366' }
}) {
Image('message_icon.png')
}
}
🚀 进阶功能：秀到飞起！ 1️⃣ 粘性标题（通讯录必备）
xxxxxxxxxx
List() {
ForEach(groups, (group) => {
ListItemGroup({ header: this.renderHeader(group.title) }) {
// 分组内容...
}
})
}
.sticky(StickyStyle.Header) // 🎯 关键代码
2️⃣ 侧滑删除（微信同款）
xxxxxxxxxx
ListItem()
.swipeAction({
end: {
builder: () => {
Button('删除')
.backgroundColor('#FF3B30')
.onClick(() => { /* 删除逻辑 */ })
}
}
})
3️⃣ 滚动条：智能显隐 List() { ... } .scrollBar(BarState.Auto) // 触摸时出现，2秒后自动隐藏
🚀 API10+ 默认开启，老项目记得检查兼容性！
🎪 高级定制功能 分组列表：像整理文件夹 // 分组头部组件 @Builder groupHeader(title: string) { Text(title) .fontSize(18) .backgroundColor('#F5F5F5') .padding(10) }
List() { ListItemGroup({ header: this.groupHeader('好友') }) { // 好友列表项... } ListItemGroup({ header: this.groupHeader('同事') }) { // 同事列表项... } }
滚动控制：瞬间移动！ private scroller = new Scroller()
// 绑定滚动控制器 List({ scroller: this.scroller }) { ... }
// 一键回顶部 Button('↑').onClick(() => { this.scroller.scrollToIndex(0) // 跳转到第一个项 })
下拉刷新：数据实时更新 // 推荐使用Refresh组件 Refresh({ refreshing: false }) { List() { ... } } .onStateChange((refreshStatus: RefreshStatus) => { // 处理刷新逻辑 })
🛠️ 编辑模式秘籍 1️⃣ 长按进入编辑模式 ListItem() .gesture( LongPressGesture() .onAction(() => { this.isEditMode = true // 开启编辑模式 }) )
2️⃣ 批量删除操作 // 勾选多项 Checkbox() .onChange((checked) => { if (checked) selectedItems.push(item) else selectedItems.remove(item) })
// 删除全部选中项 Button('删除').onClick(() => { this.data = this.data.filter(item => !selectedItems.includes(item)) })
⚡ 性能优化指南 懒加载 + 缓存策略 List() { LazyForEach(this.bigData, (item) => { ListItem() { ... } }) } .cachedCount(5) // 缓存前后5项 📊 缓存策略对比 模式 优点 缺点 循环渲染 实现简单 内存占用高 懒加载 内存优化 需要处理缓存逻辑
🎁 总结表格：一图掌握所有API
功能
核心API
应用场景
分隔线
.divider()
列表项视觉分割
粘性标题
.sticky()
通讯录/分类导航
侧滑操作
.swipeAction()
消息列表删除
滚动控制
Scroller
快速跳转定位
现在就动手打造你的专属列表吧！ 🚀 遇到问题随时回来查表~
📚 速查表：一图流总结
功能
关键API
应用场景
多列布局
.lanes()
商品列表/相册
分组展示
ListItemGroup
通讯录/分类导航
滚动控制
Scroller
返回顶部/快速跳转
侧滑交互
.swipeAction()
消息列表删除
懒加载优化
LazyForEach+cachedCount
超长列表渲染
🎉 现在就去打造你的专属列表吧！有问题随时回来查~ 👉 小作业：试着用List实现一个电影排行榜，带评分星星⭐️和分隔线！
