HarmonyOSNext列表开发指南

##Harmony OS Next ##Ark Ts ##教育 本文适用于教育科普行业进行学习，有错误之处请指出我会修改。

---

🎯 列表基础：你的数据管家

列表就像 ​​智能收纳盒​​！内容太多时自动滚动，超适合展示：

• 通讯录 👥
• 音乐歌单 🎵
• 购物车 🛒
• 新闻流 📰

✨ 核心超能力

List() {
  // 三种姿势任你选 ↓↓↓
  ListItem()      // 单个元素
  ForEach(...)    // 循环渲染
  ListItemGroup() // 分组显示
}
.scrollBar(BarState.Auto) // 自动滚动条

---

🧭 布局与约束：方向感很重要！

📏 主轴 vs 交叉轴

列表类型	主轴方向	交叉轴方向	示例场景
垂直列表	垂直 ↓	水平 →	朋友圈动态
水平列表	水平 →	垂直 ↓	电影海报墙

⚡ 黄金法则

主轴尺寸不够时自动撑开，超过父容器就截断！ 交叉轴默认占满父容器（想改？看这里 ↓↓↓）

---

🛠️ 开发四步曲

1️⃣ 设置滚动方向

// 默认垂直滚动（不用写参数）
List() { ... }

// 水平滚动超简单！
List() { ... }
.listDirection(Axis.Horizontal) // ← 关键参数

2️⃣ 多列布局神器

// 两列垂直列表
List() { ... }
.lanes(2) // 🎯 自适应列数
.alignListItem(ListItemAlign.Center) // 居中对齐

💡 超实用技巧

用 lanes: {minLength:200, maxLength:300} 自动适配不同屏幕！ 平板秒变两列，手机单列显示~

---

🎮 动态数据绑定：告别重复代码！

联系人列表实战

// 数据类
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️⃣ 添加分隔线

List() { ... }
.divider({
  strokeWidth: 1,          // 线宽
  startMargin: 60,        // 左边距
  endMargin: 10,          // 右边距
  color: '#F0F0F0'        // 颜色
})

2️⃣ 小红点标记

ListItem() {
  Badge({ 
    count: 3, 
    position: BadgePosition.RightTop,
    style: { badgeSize: 16, badgeColor: '#FF3366' }
  }) {
    Image('message_icon.png')
  }
}

---

🚀 进阶功能：秀到飞起！

1️⃣ 粘性标题（通讯录必备）

List() {
  ForEach(groups, (group) => {
    ListItemGroup({ header: this.renderHeader(group.title) }) {
      // 分组内容...
    }
  })
}
.sticky(StickyStyle.Header) // 🎯 关键代码

2️⃣ 侧滑删除（微信同款）

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实现一个电影排行榜，带评分星星⭐️和分隔线！