List:

这是列表的容器组件。它负责管理其内部所有 ListItem 的布局、滚动以及关键的性能优化机制（如循环渲染）。

你可以设置其方向（默认垂直，可设置水平 listDirection: Axis.Horizontal）、边距、宽度/高度等属性。

ListItem:

代表 List 中的单个数据项。每个 ListItem 包裹着你为该项设计的自定义内容。

List 会为数据源中的每一项创建一个 ListItem（或在滚动时复用）。

它是 List 的直接子组件。

构建你的第一个列表

代码示例：

// 1. 导入必要的模块

import { List, ListItem, Text } from '@kit.ArkUI';

@Entry

@Component

struct MyList {

  // 2. 准备数据源（这里是一个简单的字符串数组）

  private dataItems: string[] = ['Item 1', 'Item 2', 'Item 3', 'Item 4', 'Item 5'];

  build() {

    Column() {

      // 3. 创建 List 容器

      List({ space: 10 }) { // space 设置 ListItem 之间的间距

        // 4. 使用 ForEach 遍历数据源，为每一项创建 ListItem

        ForEach(this.dataItems, (item: string, index?: number) => {

          ListItem() {

            // 5. 在 ListItem 内部构建该项的 UI (这里是一个简单的 Text)

            Text(item)

              .fontSize(20)

              .padding(10)

          }

          // 6. (可选但推荐) 为 ListItem 添加唯一标识 key，对于复杂数据源尤其重要，提升性能

          .key(item) // 如果 item 本身唯一，可以直接用；否则使用 id 等唯一字段

        })

      }

      .width('100%') // List 宽度撑满父容器

      .height('100%') // List 高度撑满父容器

      .layoutWeight(1) // 在 Column 中占据剩余空间

      .divider({ // (可选) 添加分隔线

        strokeWidth: 1,

        color: '#F1F3F5',

        startMargin: 20, // 分隔线起始端缩进

        endMargin: 20    // 分隔线结束端缩进

      })

    }

    .width('100%')

    .height('100%')

    .padding(12)

  }}

水平列表

代码示例：

List({ space: 10, initialIndex: 0 }) {

  ForEach(this.dataItems, (item: string) => {

    ListItem() {

      Text(item).fontSize(20).padding(10)

    }

    .key(item)

  })

}

.listDirection(Axis.Horizontal) // 关键：设置为水平方向

.width('100%')

.height(100) // 水平列表通常需要固定高度

点击事件 :

代码示例：

ListItem() {

  Text(item).fontSize(20).padding(10)

}

.key(item)

.onClick(() => {

  console.log(`Clicked item: ${item}`);

  // 处理点击逻辑，例如导航到详情页

})

滑动操作

代码示例：

ListItem() {

  Text(item).fontSize(20).padding(10)

}

.key(item)

.swipeAction({

  end: this.EndSwipeView(item), // 定义向左滑动时显示的视图 (通常是一个自定义组件，包含删除/收藏等按钮)

})

你需要在组件中实现 EndSwipeView 构建器来定义滑动后出现的操作按钮视图。

复杂 ListItem 布局：

代码示例：

ListItem 内部可以放置任何 ArkUI 组件，构建复杂的 UI：

ListItem() {

  Row() {

    Image($r('app.media.icon')) // 左边图标

      .width(40)

      .height(40)

      .margin(10)

    Column() {

   Text(item.title)

.fontSize(18)

.fontWeight(FontWeight.Bold) // 标题

      Text(item.description).fontSize(14).opacity(0.6) // 描述

    }

    .layoutWeight(1) // 让中间文本部分占据剩余空间

Text(item.time)

.fontSize(12)

.margin(10) // 右边时间

  }

  .padding(5)

}

.key(item.id)

        List 组件是构建 HarmonyOS Next 应用界面的核心构件之一。理解其作为容器 (List) 和项 (ListItem) 的关系，掌握通过 ForEach 绑定数据源并提供唯一 key 的基础模式，并深刻理解其内置的循环渲染性能优化机制，是高效开发列表界面的关键。多实践，尝试构建不同复杂度的 ListItem 布局，并利用开发者工具的性能分析功能来优化你的列表体验！