OpenHarmony ListView如何定制

在 OpenHarmony（ArkUI） 里，早期叫 ListView，在 ArkTS / eTS 新架构中通常对应的是 List + ListItem / ListItemGroup 组件。下面从基础用法 → 常见定制方式给你系统讲一下。

一、基础 ListView（List）用法

@Entry
@Component
struct ListViewExample {
  private data: string[] = ['A', 'B', 'C', 'D']

  build() {
    List() {
      ForEach(this.data, (item: string) => {
        ListItem() {
          Text(item)
            .fontSize(20)
            .padding(10)
        }
      })
    }
    .width('100%')
    .height('100%')
  }
}

二、常见定制方式

1️⃣ 自定义 Item 布局（最常用）

ListItem() {
  Row() {
    Image($r('app.media.icon'))
      .width(40)
      .height(40)
    Text(item)
      .margin({ left: 10 })
  }
  .padding(10)
}

✅ 可任意组合：

• Text / Image / Button
• Row / Column / Stack

2️⃣ 设置滚动方向（横向 / 纵向）

List() {
  // items
}
.listDirection(Axis.Horizontal) // 横向

默认是 Axis.Vertical

3️⃣ 分割线（divider）

List() {
  // items
}
.divider({
  strokeWidth: 1,
  color: '#eee',
  startMargin: 10,
  endMargin: 10
})

4️⃣ 列表分组（ListItemGroup）

List() {
  ListItemGroup({ header: this.groupHeader('Group 1') }) {
    ListItem() { Text('Item 1') }
    ListItem() { Text('Item 2') }
  }
}

@Builder
groupHeader(title: string) {
  Text(title)
    .fontSize(18)
    .fontWeight(FontWeight.Bold)
    .padding(10)
}

5️⃣ 点击事件

ListItem() {
  Text(item)
}
.onClick(() => {
  console.log('clicked:', item)
})

6️⃣ 下拉刷新 / 上拉加载（自定义）

OpenHarmony 没有内置 Refresh 组件（旧版本），可这样实现：

下拉刷新（示例思路）

List() {
  // header
  ListItem() {
    Text('下拉刷新...')
  }
}
.onScrollIndex((start, end) => {
  if (start === 0) {
    // 触发刷新
  }
})

✅ 新版本可用 Refresh 组件（API 10+）

Refresh({ refreshing: this.isRefreshing }) {
  List() {
    // items
  }
}
.onRefreshing(() => {
  // 加载数据
})

7️⃣ 性能优化（关键）

✅ 使用 cachedCount

List() {
  // items
}
.cachedCount(5)

✅ 大数据用 LazyForEach

List() {
  LazyForEach(this.dataSource, (item) => {
    ListItem() {
      Text(item)
    }
  })
}

三、旧版 ListView（JS / eTS 兼容）

旧版：

<list>
  <list-item for="{{list}}">
    <text>{{$item}}</text>
  </list-item>
</list>

⚠️ 新项目不推荐，建议用 ArkTS

四、总结

如果你有 具体场景（比如聊天列表、设置页、瀑布流、RecyclerView 迁移），我可以给你完整示例代码。