HarmonyOS6 ArkTS ListItemGroup设置Header/Footer

文章目录一、核心概念与配置方式1. 两种配置方式对比2. 核心属性优先级3. 接口说明二、Header/Footer核心配置与API1. 传统配置header/footer2. 新版配置headerComponent/footerComponent3. 构建器参数封装三、完整实现示例1. 代码实现四、功能效果与核心逻辑说明1. 基础效果2. 动态更新逻辑3. 组件层级约束4. 新版配置ComponentContent约束5. 样式与布局约束6. 动态更新约束7. 吸顶/吸底联动约束总结一、核心概念与配置方式1. 两种配置方式对比ListItemGroup提供传统Builder和新版ComponentContent两种Header/Footer配置方式二者可单独使用新版方式优先级更高且支持动态更新具体对比如下配置方式对应属性基于类型核心特性API版本动态更新传统方式header/footerCustomBuilder静态配置简单易用9不支持新版方式headerComponent/footerComponentComponentContent动态更新灵活扩展13支持2. 核心属性优先级当同时配置传统header/footer和新版headerComponent/footerComponent时新版属性优先级更高系统会优先渲染headerComponent/footerComponent对应的内容传统属性会被忽略。3. 接口说明ComponentContentAPI 13新增的组件内容封装类支持传入构建器、参数并实现动态更新是新版Header/Footer的核心载体wrapBuilder将自定义Builder构建器转换为ComponentContent可识别的构建器类型实现Builder与ComponentContent的适配IDataSourceLazyForEach的数据源接口通过notifyDataChange实现数据更新后UI的联动刷新。二、Header/Footer核心配置与API1. 传统配置header/footer语法ListItemGroup({header:自定义Builder构建器,footer:自定义Builder构建器})2. 新版配置headerComponent/footerComponent核心语法// 初始化ComponentContentnewComponentContent(this.getUIContext(),wrapBuilder(自定义Builder),构建器参数)// ListItemGroup配置ListItemGroup({headerComponent:初始化后的ComponentContent实例,footerComponent:初始化后的ComponentContent实例})更新方法// 动态更新ComponentContent的参数componentContent实例?.update(新的构建器参数)3. 构建器参数封装通过自定义类封装Builder的入参实现参数的统一管理和动态传递语法示例// 头部参数封装classHeadBuilderParams{text:string|Resource;constructor(text:string|Resource){this.texttext;}}三、完整实现示例1. 代码实现import{ComponentContent}fromkit.ArkUI;import{TimeTable,ProjectsDataSource,TimeTableDataSource}from./ListDataSource;// 头部构建器参数封装分组标题classHeadBuilderParams{text:string|Resource;constructor(text:string|Resource){this.texttext;}}// 尾部构建器参数封装课程数量统计classFootBuilderParams{num:number|Resource;constructor(num:number|Resource){this.numnum;}}// 头部自定义构建器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))}// 自定义分组组件封装ListItemGroup与Header/FooterComponentstruct MyItemGroup{item:TimeTable{title:,projects:[]};header?:ComponentContentHeadBuilderParamsundefined;footer?:ComponentContentFootBuilderParamsundefined;headerParamnewHeadBuilderParams(this.item.title);footerParamnewFootBuilderParams(this.item.projects.length);itemArr:ProjectsDataSourcenewProjectsDataSource([]);// 初始化ComponentContentaboutToAppear():void{this.headernewComponentContent(this.getUIContext(),wrapBuilder(itemHead),this.headerParam);this.footernewComponentContent(this.getUIContext(),wrapBuilder(itemFoot),this.footerParam);this.itemArrnewProjectsDataSource(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(){// 核心配置headerComponent/footerComponentListItemGroup({headerComponent:this.GetHeader(),footerComponent:this.GetFooter()}){// 懒加载分组子项LazyForEach(this.itemArr,(project:string){ListItem(){Text(project).width(100%).height(100).fontSize(20).textAlign(TextAlign.Center)}},(item:string)item)}.divider({strokeWidth:1,color:Color.Blue})// 子项分割线}}// 主页面组件EntryComponentstruct Index{itemGroupArray:TimeTableDataSourcenewTimeTableDataSource([]);// 初始化分组数据源aboutToAppear():void{lettimeTable:TimeTable[][{title:星期一,projects:[语文,数学,英语]},{title:星期二,projects:[物理,化学,生物]},{title:星期三,projects:[历史,地理,政治,体育]},{title:星期四,projects:[美术,音乐]}];this.itemGroupArraynewTimeTableDataSource(timeTable);}build(){Column(){// 数据更新按钮修改第一个分组的Header/Footer内容Button(update).width(100).height(50).onClick((){this.itemGroupArray.change1stItem({title:更新后的星期一,projects:[语文,物理,历史,美术]});})// List容器开启吸顶/吸底List({space:20}){LazyForEach(this.itemGroupArray,(item:TimeTable){MyItemGroup({item:item})},(item:TimeTable)item.title)// 依赖title作为键值实现UI刷新}.layoutWeight(1).sticky(StickyStyle.Header|StickyStyle.Footer)// Header吸顶、Footer吸底.scrollBar(BarState.Off)}.backgroundColor($r(sys.color.background_primary))}}运行效果如图滑动的时候可以观察到四、功能效果与核心逻辑说明1. 基础效果Header展示每个分组的标题如“星期一”“星期二”使用系统次级背景色固定高度48vp宽度充满父容器Footer展示每个分组的课程数量统计如“共3节课”与Header样式统一实现视觉一致性分割线通过divider属性为分组内子项添加蓝色1px分割线提升列表层次感吸顶/吸底通过List的sticky属性实现Header吸顶、Footer吸底滚动时保持分组标识可见。2. 动态更新逻辑点击update按钮调用数据源的change1stItem方法修改第一个分组的标题和课程列表数据源通过notifyDataChange(0)通知UI层数据更新LazyForEach根据item.title作为键值识别到数据变化后刷新对应的MyItemGroup组件MyItemGroup的GetHeader/GetFooter方法调用ComponentContent的update方法传递新的参数Header/Footer根据新参数重新渲染实现动态更新标题和统计数据。3. 组件层级约束ListItemGroup必须作为List的直接子组件不可嵌套在Column、Row等其他容器中否则Header/Footer配置失效Header/Footer的宽度默认与List保持一致手动设置宽度可能导致布局错乱建议使用width(100%)。4. 新版配置ComponentContent约束同一个ComponentContent实例不推荐同时给不同的ListItemGroup使用否则会导致显示错乱、更新异常初始化ComponentContent时必须传入当前组件的UI上下文this.getUIContext()否则无法正常渲染wrapBuilder函数仅用于转换Builder构建器不可直接传入组件实例。5. 样式与布局约束当List的listDirection为Axis.Vertical默认时ListItemGroup的height属性不生效高度由Header高度Footer高度所有子项高度自动计算Header/Footer与子项之间无默认间距如需调整可在Builder中通过padding/margin实现space属性仅作用于子项之间建议为Header/Footer设置固定高度避免动态高度导致的滚动卡顿和布局偏移。6. 动态更新约束使用LazyForEach时必须指定唯一的键值如示例中的item.title否则数据更新后UI无法正常刷新数据源修改后必须调用notifyDataChange方法通知UI层否则ComponentContent的update方法无效新版配置仅支持API 13及以上版本低版本需使用传统header/footer配置。7. 吸顶/吸底联动约束Header/Footer的吸顶/吸底效果由List的sticky属性控制ListItemGroup自身无独立配置吸顶/吸底的Header/Footer会覆盖List的顶部/底部区域建议避免在Header/Footer中添加可点击的高频操作按钮防止遮挡。总结ListItemGroup的Header/Footer有传统Builder和新版ComponentContent两种配置方式新版支持动态更新且优先级更高新版配置的核心是ComponentContent类通过wrapBuilder实现与自定义Builder的适配通过update方法实现动态参数修改动态更新需配合IDataSource和LazyForEach通过数据通知和唯一键值实现UI与数据的联动Header/Footer可与吸顶/吸底、分割线、卡片样式等功能结合实现多样化的分组列表效果开发时需遵循组件层级、版本兼容、实例复用等约束保证布局稳定和性能优化。如果这篇文章对你有帮助欢迎点赞、收藏、关注你的支持是持续创作的动力