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

HarmonyOS6 ArkTS ListItemGroup设置多列布局

news 2026/7/25 18:01:35

文章目录

- 一、核心概念
- - 1. 多列布局原理
  - 2. 关键属性
- 二、多列布局核心配置
- - 1. List配置列数
  - 2. 子项对齐配置
  - 3. ListItemGroup适配
- 三、完整实现示例
- 五、多列布局效果与规则
- - 1. 界面展示效果
  - 2. 布局规则
- 总结

一、核心概念

1. 多列布局原理

配置入口：多列布局不由ListItemGroup控制，而是由其父容器List通过lanes属性统一配置；
作用范围：lanes配置后，List内所有ListItemGroup的子项都会自动按指定列数排列；
布局规则：系统自动计算子项宽度，平均分配列空间，自动换行展示。

2. 关键属性

lanes：List的核心属性，设置纵向滚动时的列数，取值为正整数，默认1（单列）；
alignListItem：List属性，设置子项在交叉轴（列方向）的对齐方式，支持Start/Center/End；
ListItemGroup：仅作为分组容器，承载子项与Header/Footer，不参与列数计算。

二、多列布局核心配置

1. List配置列数

通过lanes属性设置列数，是实现多列布局的唯一入口：

List(){// ListItemGroup + 子项}.lanes(3)// 设置3列布局

2. 子项对齐配置

通过alignListItem优化多列子项的对齐效果：

List().lanes(3).alignListItem(ListItemAlign.Center)// 子项在列内居中对齐

3. ListItemGroup适配

ListItemGroup无需额外配置，Header/Footer会自动铺满整行，子项自动按列排列：

头部Header：独占一行，宽度100%
子项ListItem：自动分配列宽，多列排列
尾部Footer：独占一行，宽度100%

三、完整实现示例

// xxx.etsimport{ComponentContent}from'@kit.ArkUI';import{TimeTable,ProjectsDataSource,TimeTableDataSource}from'./ListDataSource';// 头部参数类classHeadBuilderParams{text:string|Resource;constructor(text:string|Resource){this.text=text;}}// 尾部参数类classFootBuilderParams{num:number|Resource;constructor(num:number|Resource){this.num=num;}}// 头部构建器@BuilderfunctionitemHead(params:HeadBuilderParams){Text(params.text).fontSize(20).height('48vp').width('100%').padding(10).backgroundColor($r('sys.color.background_tertiary'))}// 尾部构建器@BuilderfunctionitemFoot(params:FootBuilderParams){Text('共'+params.num.toString()+'节课').fontSize(20).height('48vp').width('100%').padding(10).backgroundColor($r('sys.color.background_tertiary'))}// 自定义分组组件@Componentstruct MyItemGroup{item:TimeTable={title:'',projects:[]};header?:ComponentContent<HeadBuilderParams>=undefined;footer?:ComponentContent<FootBuilderParams>=undefined;headerParam=newHeadBuilderParams(this.item.title);footerParam=newFootBuilderParams(this.item.projects.length);itemArr:ProjectsDataSource=newProjectsDataSource([]);aboutToAppear():void{this.header=newComponentContent(this.getUIContext(),wrapBuilder(itemHead),this.headerParam);this.footer=newComponentContent(this.getUIContext(),wrapBuilder(itemFoot),this.footerParam);this.itemArr=newProjectsDataSource(this.item.projects);}GetHeader(){this.header?.update(newHeadBuilderParams(this.item.title));returnthis.header;}GetFooter(){this.footer?.update(newFootBuilderParams(this.item.projects.length));returnthis.footer;}build(){// ListItemGroup 无需配置列数，自动适配父级List的lanesListItemGroup({headerComponent:this.GetHeader(),footerComponent:this.GetFooter()}){LazyForEach(this.itemArr,(project:string)=>{ListItem(){Column(){Text(project).fontSize(20).textAlign(TextAlign.Center)}.width('100%').height(80).padding(8).justifyContent(FlexAlign.Center).backgroundColor($r('sys.color.background_secondary')).borderRadius(12).shadow({radius:4,color:'#20000000',offsetX:0,offsetY:2})}},(item:string)=>item)}// 分组内分割线配置.divider({strokeWidth:2,color:$r('sys.color.background_tertiary'),startMargin:20,endMargin:20})}}// 主页面@Entry@Componentstruct ListItemGroupExample{itemGroupArray:TimeTableDataSource=newTimeTableDataSource([]);aboutToAppear():void{lettimeTable:TimeTable[]=[{title:'星期一',projects:['语文','数学','英语','物理','化学','生物']},{title:'星期二',projects:['历史','地理','政治','体育','美术','音乐']},{title:'星期三',projects:['计算机','编程','算法','数据结构','网络']},{title:'星期四',projects:['文学','写作','阅读','书法']},{title:'星期五',projects:['实验','生活','奥数','高数','中医']}];this.itemGroupArray=newTimeTableDataSource(timeTable);}build(){Column(){// 核心：List配置 lanes=3 实现3列布局List({space:15}){LazyForEach(this.itemGroupArray,(item:TimeTable)=>{MyItemGroup({item:item})},(item:TimeTable)=>item.title)}.lanes(3)// 多列布局核心配置.alignListItem(ListItemAlign.Center)// 子项居中对齐.layoutWeight(1).scrollBar(BarState.Auto).width('100%').margin(10)}.backgroundColor($r('sys.color.background_primary')).width('100%').height('100%').padding(10)}}