9.ArkUI List的介绍和使用

ArkUI List 组件详解与使用指南

List 是 ArkUI（HarmonyOS 开发框架）中用于展示长列表数据的高性能滚动容器组件。以下是 List 的详细介绍和使用方法。

基本介绍

List 组件特点：

• 支持垂直/水平滚动
• 高性能渲染（仅渲染可视区域内的项）
• 支持多种布局方式
• 内置多种滑动操作和交互效果

基本使用

1. 简单列表

@Entry
@Component
struct SimpleListExample {
  private data: string[] = ['Apple', 'Banana', 'Orange', 'Pear', 'Grape']

  build() {
    Column() {
      List({ space: 10 }) {
        ForEach(this.data, (item: string) => {
          ListItem() {
            Text(item)
              .fontSize(20)
              .width('100%')
              .textAlign(TextAlign.Center)
              .backgroundColor('#f0f0f0')
              .padding(10)
          }
        }, (item: string) => item)
      }
      .width('100%')
      .height('100%')
    }
  }
}

2. 复杂列表项

@Entry
@Component
struct ComplexListExample {
  private contacts = [
    { name: '张三', phone: '13800138000', avatar: 'user1.png' },
    { name: '李四', phone: '13900139000', avatar: 'user2.png' },
    // 更多数据...
  ]

  build() {
    List({ space: 5 }) {
      ForEach(this.contacts, (contact) => {
        ListItem() {
          Row() {
            Image(contact.avatar)
              .width(50)
              .height(50)
              .borderRadius(25)
            
            Column() {
              Text(contact.name)
                .fontSize(18)
                .fontWeight(FontWeight.Bold)
              Text(contact.phone)
                .fontSize(14)
                .fontColor('#666')
            }.margin({ left: 10 })
          }
          .width('100%')
          .padding(10)
        }
      }, contact => contact.phone)
    }
    .width('100%')
    .height('100%')
  }
}

核心功能

1. 列表方向

List() {
  // 列表项
}
.layoutDirection(Axis.Vertical) // 垂直列表（默认）

List() {
  // 列表项
}
.layoutDirection(Axis.Horizontal) // 水平列表

2. 列表分隔线

List() {
  // 列表项
}
.divider({
  strokeWidth: 1,
  color: '#f0f0f0',
  startMargin: 20,
  endMargin: 20
})

3. 列表滚动控制

@State scroller: Scroller = new Scroller()

build() {
  List({ scroller: this.scroller }) {
    // 列表项
  }
  
  // 滚动到指定位置
  Button('滚动到底部')
    .onClick(() => {
      this.scroller.scrollTo({ x: 0, y: 1000 })
    })
}

4. 下拉刷新和上拉加载

@State isRefreshing: boolean = false
@State isLoadingMore: boolean = false

build() {
  List() {
    // 列表项
  }
  .onScrollIndex((start, end) => {
    // 滚动到接近底部时触发加载更多
    if (end >= this.data.length - 5) {
      this.loadMore()
    }
  })
  .refresh({
    refreshing: this.isRefreshing,
    onRefresh: () => {
      this.refreshData()
    }
  })
}

private refreshData() {
  this.isRefreshing = true
  // 模拟异步请求
  setTimeout(() => {
    this.isRefreshing = false
  }, 1000)
}

private loadMore() {
  if (this.isLoadingMore) return
  this.isLoadingMore = true
  // 模拟异步加载
  setTimeout(() => {
    // 添加新数据
    this.isLoadingMore = false
  }, 1000)
}

性能优化

1. 复用标识

ForEach(this.data, (item) => {
  ListItem() {
    // 内容
  }
}, (item) => item.id) // 提供唯一键提高复用效率

2. 懒加载

ListItem() {
  LazyForEach(this.dataSource, (item) => {
    // 列表项内容
  }, (item) => item.id)
}

3. 固定高度

ListItem() {
  // 内容
}
.height(80) // 指定固定高度提高性能

高级功能

1. 分组列表

@Entry
@Component
struct SectionListExample {
  private sections = [
    {
      title: 'A',
      data: ['Apple', 'Apricot', 'Avocado']
    },
    {
      title: 'B',
      data: ['Banana', 'Blackberry', 'Blueberry']
    }
    // 更多分组...
  ]

  build() {
    List() {
      ForEach(this.sections, (section) => {
        ListItemGroup({ header: this.renderHeader(section.title) }) {
          ForEach(section.data, (item) => {
            ListItem() {
              Text(item)
                .padding(10)
            }
          })
        }
      })
    }
  }

  @Builder renderHeader(title: string) {
    Text(title)
      .fontSize(18)
      .fontWeight(FontWeight.Bold)
      .backgroundColor('#f0f0f0')
      .width('100%')
      .padding(10)
  }
}

2. 滑动操作

ListItem() {
  // 主内容
}
.swipeAction({ 
  end: this.DeleteButton(),
  start: this.MarkButton() 
})

@Builder DeleteButton() {
  Button('删除')
    .width(80)
    .height('100%')
    .backgroundColor(Color.Red)
    .onClick(() => {
      // 删除操作
    })
}

@Builder MarkButton() {
  Button('标记')
    .width(80)
    .height('100%')
    .backgroundColor(Color.Green)
    .onClick(() => {
      // 标记操作
    })
}

最佳实践

1. 避免复杂嵌套：减少列表项的嵌套层级
2. 使用固定尺寸：尽可能为列表项指定固定高度/宽度
3. 分页加载：大数据集采用分页加载
4. 图片优化：使用缩略图或懒加载大图片
5. 减少状态更新：避免频繁更新列表数据

通过合理使用 List 组件，可以构建出高性能、流畅滚动的列表界面。