OpenHarmony列表组件如何布局

在 OpenHarmony（ArkUI） 中，列表组件主要通过 List + ListItem 来实现，也可以用 Grid 做网格布局。下面从基础布局、常用属性、常见布局方式几个方面说明。

一、最基础的 List 布局

1. 垂直列表（默认）

List() {
  ListItem() {
    Text('Item 1')
  }
  ListItem() {
    Text('Item 2')
  }
  ListItem() {
    Text('Item 3')
  }
}

✅ 默认方向：Axis.Vertical

2. 水平列表

List() {
  ListItem() {
    Text('A')
  }
  ListItem() {
    Text('B')
  }
}
.listDirection(Axis.Horizontal)

二、List 常用布局属性

List() {
  // ListItem...
}
.listDirection(Axis.Vertical)      // 列表方向
.alignListItem(ListItemAlign.Center) // 子项对齐
.scrollBar(BarState.Auto)          // 滚动条
.edgeEffect(EdgeEffect.Spring)     // 边缘效果
.width('100%')
.height('100%')

三、ListItem 内部布局（重点）

ListItem 本身只是一个容器，内部布局靠 Flex / Column / Row

1. 左图标 + 右文字

ListItem() {
  Row() {
    Image($r('app.media.icon'))
      .width(40)
      .height(40)

    Text('标题')
      .margin({ left: 12 })
  }
  .width('100%')
  .padding(12)
}

2. 上下结构（标题 + 描述）

ListItem() {
  Column() {
    Text('标题').fontSize(16)
    Text('描述信息').fontSize(12).fontColor('#999')
  }
  .alignItems(HorizontalAlign.Start)
  .padding(12)
}

四、等分 / 网格布局（Grid）

如果是多列布局，推荐用 Grid：

Grid() {
  ForEach([1,2,3,4,5,6], (item) => {
    GridItem() {
      Text('Item ' + item)
    }
  })
}
.columnsTemplate('1fr 1fr')
.rowsTemplate('1fr 1fr 1fr')

五、常见列表布局模板

✅ 设置项列表

List() {
  ListItem() {
    Row() {
      Text('Wi-Fi')
      Blank()
      Toggle({ type: ToggleType.Switch, isOn: true })
    }
    .padding(16)
  }
}

✅ 卡片列表

List() {
  ListItem() {
    Column() {
      Text('标题')
      Text('内容')
    }
    .padding(16)
    .backgroundColor('#FFF')
    .borderRadius(12)
    .margin(8)
  }
}

六、性能建议（重要）

• ✅ 使用 ForEach 渲染列表
• ✅ 长列表用 LazyForEach
• ✅ 避免 ListItem 中嵌套复杂布局

List() {
  ForEach(this.data, (item) => {
    ListItem() {
      Text(item)
    }
  })
}

如果你有具体需求（比如：聊天列表、商品列表、左滑删除、瀑布流），可以告诉我，我可以直接给你完整示例。