当前位置：首页 > news >正文

HarmonyOS6 ArkTS 创建ListItem

news 2026/4/4 4:54:58

文章目录

- 1. 核心依赖与前提
- - 1.1 组件约束
  - 1.2 适用版本
- 2. 完整标准代码：
- 3. ListItem 创建与使用详解
- - 3.1 基础创建语法（核心）
  - 3.2 必须依赖的父容器
  - 3.3 结合 LazyForEach 批量创建（高性能方案）
  - 3.4 数据适配器（ListDataSource）作用
- 4. ListItem 常用样式配置
- - 核心属性说明
- 5. 运行效果
- 总结

ListItem是列表布局的基础单元组件，必须嵌套在List容器中使用，用于展示列表中的单行内容，支持文本、图标、自定义布局、点击交互等场景，是应用开发中高频使用的基础组件。

1. 核心依赖与前提

1.1 组件约束

ListItem只能作为List的直接子组件，不可独立使用；
配合LazyForEach实现大数据列表的懒加载优化；
依赖IDataSource接口实现数据驱动列表渲染。

1.2 适用版本

HarmonyOS 6 / API 14及以上

2. 完整标准代码：

// xxx.ets // 1. 定义数据适配器，实现IDataSource接口 export class ListDataSource implements IDataSource { private list: number[] = []; constructor(list: number[]) { this.list = list; } // 获取列表总数据量 totalCount(): number { return this.list.length; } // 根据索引获取对应数据 getData(index: number): number { return this.list[index]; } // 注册数据变化监听 registerDataChangeListener(listener: DataChangeListener): void { } // 注销数据变化监听 unregisterDataChangeListener(listener: DataChangeListener): void { } } // 2. 页面组件：List + ListItem 标准使用 @Entry @Component struct ListItemExample { // 初始化数据源 private arr: ListDataSource = new ListDataSource([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); build() { Column() { // List容器配置：间距20，默认起始索引0 List({ space: 20, initialIndex: 0 }) { // 懒加载遍历数据，渲染ListItem LazyForEach(this.arr, (item: number) => { // ========== 核心：创建标准ListItem ========== ListItem() { Text('' + item) .width('100%') .height(100) .fontSize(16) .textAlign(TextAlign.Center) .borderRadius(10) .backgroundColor(0xFFFFFF) } }, (item: string) => item) }.width('90%') .scrollBar(BarState.Off) // 隐藏滚动条 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) } }

运行效果如图：

3. ListItem 创建与使用详解

3.1 基础创建语法（核心）

ListItem采用闭包语法创建，内部可包裹任意子组件（Text/Image/Row/Column等）：

ListItem() { // 列表项内容（子组件） Text("列表项内容") }

这是ListItem最基础的创建方式，也是官方文档推荐的标准写法。

3.2 必须依赖的父容器

ListItem无法单独渲染，必须放在List组件内部：

List() { // 可创建多个ListItem ListItem() { Text("项1") } ListItem() { Text("项2") } }

3.3 结合 LazyForEach 批量创建（高性能方案）

在长列表场景中，使用LazyForEach+IDataSource实现按需渲染，避免性能损耗，这是鸿蒙开发的最佳实践：

遍历数据源this.arr
为每一条数据自动创建一个ListItem
第三个参数为唯一标识，优化渲染性能

LazyForEach(this.arr, (item: number) => { ListItem() { // 自定义列表项内容 } }, (item: string) => item)

3.4 数据适配器（ListDataSource）作用

实现IDataSource接口，为ListItem提供标准化数据：

totalCount()：返回列表总项数，决定ListItem的创建数量
getData(index)：根据索引返回对应数据，绑定到ListItem
监听方法：用于数据更新时刷新列表（基础场景可空实现）

4. ListItem 常用样式配置

基于官方文档，ListItem支持丰富的样式定制，可直接在组件后链式调用属性，示例：

ListItem() { Text('' + item) } .width('100%') // 宽度 .height(100) // 高度 .backgroundColor(0xFFFFFF) // 背景色 .borderRadius(10) // 圆角 .padding(10) // 内边距 .onClick(() => { // 点击事件 console.log("点击列表项：" + item) })

核心属性说明

属性	作用
`width/height`	设置列表项宽高
`backgroundColor`	设置背景颜色
`borderRadius`	设置圆角
`padding/margin`	设置内/外边距
`onClick`	列表项点击交互
`scrollBar`	配置列表滚动条（List属性）