1# ListItemGroup 2 3该组件用来展示列表item分组，宽度默认充满[List](ts-container-list.md)组件，必须配合List组件来使用。 4 5> **说明：** 6> 7> - 该组件从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> - 该组件的父组件只能是[List](ts-container-list.md)。 9> - ListItemGroup组件不支持设置[通用属性aspectRatio](ts-universal-attributes-layout-constraints.md)。 10> - 当ListItemGroup的父组件List的listDirection属性为Axis.Vertical时，设置[通用属性height](ts-universal-attributes-size.md)属性不生效。ListItemGroup的高度为header高度、footer高度和所有ListItem布局后总高度之和。 11> - 当父组件List的listDirection属性为Axis.Horizontal时，设置[通用属性width](ts-universal-attributes-size.md)属性不生效。ListItemGroup的宽度为header宽度、footer宽度和所有ListItem布局后总宽度之和。 12> - 当前ListItemGroup内部的ListItem组件不支持编辑、拖拽功能，即ListItem组件的editable属性不生效。 13> - ListItemGroup使用direction属性设置布局方向不生效，ListItemGroup组件布局方向跟随父容器List组件的布局方向。 14 15## 子组件 16 17包含[ListItem](ts-container-listitem.md)子组件。 18 19 20## 接口 21 22ListItemGroup(options?: ListItemGroupOptions) 23 24**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 25 26**系统能力：** SystemCapability.ArkUI.ArkUI.Full 27 28**参数：** 29 30| 参数名 | 类型 | 必填 | 说明 | 31| -------- | -------- | -------- | -------- | 32| options | [ListItemGroupOptions](#listitemgroupoptions对象说明)| 否 | 列表item分组组件参数。 | 33 34## ListItemGroupOptions对象说明 35 36**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 37 38**系统能力：** SystemCapability.ArkUI.ArkUI.Full 39 40| 名称 | 类型 | 必填 | 说明 | 41| ------------------- | --------------------------------------------------- | ---- | ------------------------------------------------------------ | 42| header | [CustomBuilder](ts-types.md#custombuilder8) | 否 | 设置ListItemGroup头部组件。<br/>**说明：**<br/>可以放单个子组件或不放子组件。 | 43| headerComponent<sup>13+</sup> | [ComponentContent](../js-apis-arkui-ComponentContent.md) | 否 | 使用ComponentContent类型参数设置ListItemGroup头部组件。<br/>**说明：**<br/>可以放单个子组件或不放子组件。 该参数的优先级高于参数header。即同时设置header和headerComponent时，以headerComponent设置的值为准。<br/>同一个headerComponent不推荐同时给不同的ListItemGroup使用,否则会导致显示问题。 | 44| footer | [CustomBuilder](ts-types.md#custombuilder8) | 否 | 设置ListItemGroup尾部组件。<br/>**说明：**<br/>可以放单个子组件或不放子组件。 | 45| footerComponent<sup>13+</sup> | [ComponentContent](../js-apis-arkui-ComponentContent.md) | 否 | 使用ComponentContent类型参数设置ListItemGroup尾部组件。<br/>**说明：**<br/>可以放单个子组件或不放子组件。该参数的优先级高于参数footer。 即同时设置footer和footerComponent时，以footerComponent设置的值为准。<br/>同一个footerComponent不推荐同时给不同的ListItemGroup使用,否则会导致显示问题。 | 46| space | number \| string | 否 | 列表项间距。只作用于ListItem与ListItem之间，不作用于header与ListItem、footer与ListItem之间。<br/>默认值：0<br/>单位：vp | 47| style<sup>10+</sup> | [ListItemGroupStyle](#listitemgroupstyle10枚举说明) | 否 | 设置List组件卡片样式。<br/>默认值: ListItemGroupStyle.NONE<br/>设置为ListItemGroupStyle.NONE时无样式。<br/>设置为ListItemGroupStyle.CARD时，建议配合[ListItem](ts-container-listitem.md)的ListItemStyle.CARD同时使用，显示默认卡片样式。 <br/>卡片样式下，ListItemGroup默认规格：左右外边距12vp，上下左右内边距4vp。<br/>卡片样式下, 为卡片内的列表选项提供了默认的focus、hover、press、selected和disable样式。<br/>**说明：**<br/>当前卡片模式下，使用默认Axis.Vertical排列方向，如果listDirection属性设置为Axis.Horizontal，会导致显示混乱;List属性alignListItem默认为ListItemAlign.Center，居中对齐显示。 | 48 49## 属性 50 51### divider 52 53divider(value: {strokeWidth: Length; color?: ResourceColor; startMargin?: Length; endMargin?: Length;} | null,) 54 55设置ListItem分割线样式，默认无分割线。 56 57strokeWidth, startMargin和endMargin不支持设置百分比。 58 59ListItem设置[多态样式](ts-universal-attributes-polymorphic-style.md)时，被按压的子组件上下的分割线不绘制。 60 61**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 62 63**系统能力：** SystemCapability.ArkUI.ArkUI.Full 64 65**参数：** 66 67| 参数名 | 类型 | 必填 | 说明 | 68| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 69| value | {<br/>strokeWidth: [Length](ts-types.md#length),<br/>color?:[ResourceColor](ts-types.md#resourcecolor),<br/>startMargin?: [Length](ts-types.md#length),<br/>endMargin?: [Length](ts-types.md#length)<br/>} \| null | 是 | ListItem分割线样式。<br/>- strokeWidth: 分割线的线宽。<br/>- color: 分割线的颜色。<br/> 默认值：0x08000000<br/>- startMargin: 分割线与列表侧边起始端的距离。<br/>默认值：0，单位：vp<br/>- endMargin: 分割线与列表侧边结束端的距离。<br/>默认值：0，单位：vp | 70 71### childrenMainSize<sup>12+</sup> 72 73childrenMainSize(value: ChildrenMainSize) 74 75设置ListItemGroup组件的子组件在主轴方向的大小信息。 76 77**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 78 79**系统能力：** SystemCapability.ArkUI.ArkUI.Full 80 81**参数：** 82 83| 参数名 | 类型 | 必填 | 说明 | 84| ---------- | ------ | ---- | ------------------------------- | 85| value | [ChildrenMainSize](ts-container-scrollable-common.md#childrenmainsize12对象说明) | 是 | 1.通过ChildrenMainSize对象向ListItemGroup组件准确提供所有ListItem在主轴方向的大小信息。<br/>2.提供的主轴方向大小必须与子组件实际在主轴方向的大小一致。<br/>3. 必须同时设置List的childrenMainSize属性使用。<br/>4.子组件主轴方向大小变化或者增删子组件时都必须通过ChildrenMainSize对象方法通知ListItemGroup组件。| 86 87## ListItemGroupStyle<sup>10+</sup>枚举说明 88 89**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 90 91**系统能力：** SystemCapability.ArkUI.ArkUI.Full 92 93| 名称 | 值 | 说明 | 94| ---- | ---- | ------------------ | 95| NONE | 0 | 无样式。 | 96| CARD | 1 | 显示默认卡片样式。 | 97 98 99 100## 示例 101 102### 示例1 103 104该示例展示了ListItemGroup的header吸顶和footer吸底的效果。 105 106```ts 107// xxx.ets 108@Entry 109@Component 110struct ListItemGroupExample { 111 private timeTable: TimeTable[] = [ 112 { 113 title: '星期一', 114 projects: ['语文', '数学', '英语'] 115 }, 116 { 117 title: '星期二', 118 projects: ['物理', '化学', '生物'] 119 }, 120 { 121 title: '星期三', 122 projects: ['历史', '地理', '政治'] 123 }, 124 { 125 title: '星期四', 126 projects: ['美术', '音乐', '体育'] 127 } 128 ] 129 130 @Builder 131 itemHead(text: string) { 132 Text(text) 133 .fontSize(20) 134 .backgroundColor(0xAABBCC) 135 .width("100%") 136 .padding(10) 137 } 138 139 @Builder 140 itemFoot(num: number) { 141 Text('共' + num + "节课") 142 .fontSize(16) 143 .backgroundColor(0xAABBCC) 144 .width("100%") 145 .padding(5) 146 } 147 148 build() { 149 Column() { 150 List({ space: 20 }) { 151 ForEach(this.timeTable, (item: TimeTable) => { 152 ListItemGroup({ header: this.itemHead(item.title), footer: this.itemFoot(item.projects.length) }) { 153 ForEach(item.projects, (project: string) => { 154 ListItem() { 155 Text(project) 156 .width("100%") 157 .height(100) 158 .fontSize(20) 159 .textAlign(TextAlign.Center) 160 .backgroundColor(0xFFFFFF) 161 } 162 }, (item: string) => item) 163 } 164 .divider({ strokeWidth: 1, color: Color.Blue }) // 每行之间的分界线 165 }) 166 } 167 .width('90%') 168 .sticky(StickyStyle.Header | StickyStyle.Footer) 169 .scrollBar(BarState.Off) 170 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 171 } 172} 173 174interface TimeTable { 175 title: string; 176 projects: string[]; 177} 178``` 179 180 181 182### 示例2 183 184该示例展示了ListItemGroup的卡片样式效果。 185 186```ts 187// xxx.ets 188@Entry 189@Component 190struct ListItemGroupExample2 { 191 private arr: ArrObject[] = [ 192 { 193 style: ListItemGroupStyle.CARD, 194 itemStyles: [ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.CARD] 195 }, 196 { 197 style: ListItemGroupStyle.CARD, 198 itemStyles: [ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE] 199 }, 200 { 201 style: ListItemGroupStyle.CARD, 202 itemStyles: [ListItemStyle.CARD, ListItemStyle.NONE, ListItemStyle.CARD] 203 }, 204 { 205 style: ListItemGroupStyle.NONE, 206 itemStyles: [ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE] 207 } 208 ] 209 210 build() { 211 Column() { 212 List({ space: "4vp", initialIndex: 0 }) { 213 ForEach(this.arr, (item: ArrObject, index?: number) => { 214 ListItemGroup({ style: item.style }) { 215 ForEach(item.itemStyles, (itemStyle: number, itemIndex?: number) => { 216 ListItem({ style: itemStyle }) { 217 if (index != undefined && itemIndex != undefined) { 218 Text("第" + (index + 1) + "个Group中第" + (itemIndex + 1) + "个item") 219 .width("100%") 220 .textAlign(TextAlign.Center) 221 } 222 } 223 }, (item: string) => item) 224 } 225 }) 226 } 227 .width('100%') 228 .multiSelectable(true) 229 .backgroundColor(0xDCDCDC) 230 } 231 .width('100%') 232 .padding({ top: 5 }) 233 } 234} 235 236interface ArrObject { 237 style: number; 238 itemStyles: number[]; 239} 240``` 241 242 243### 示例3 244 245该示例通过ComponentContent设置Header/Footer。 246 247```ts 248// xxx.ets 249import { ComponentContent } from '@kit.ArkUI'; 250 251interface TimeTable { 252 title: string; 253 projects: string[]; 254} 255 256class HeadBuilderParams { 257 text: string | Resource; 258 constructor(text: string | Resource) { 259 this.text = text; 260 } 261} 262 263class FootBuilderParams { 264 num: number | Resource; 265 constructor(num: number | Resource) { 266 this.num = num; 267 } 268} 269 270@Builder 271function itemHead(params: HeadBuilderParams) { 272 Text(params.text) 273 .fontSize(20) 274 .height('48vp') 275 .width("100%") 276 .padding(10) 277 .backgroundColor($r('sys.color.background_tertiary')) 278} 279 280@Builder 281function itemFoot(params: FootBuilderParams) { 282 Text('共' + params.num + '节课') 283 .fontSize(20) 284 .height('48vp') 285 .width("100%") 286 .padding(10) 287 .backgroundColor($r('sys.color.background_tertiary')) 288} 289 290@Component 291struct MyItemGroup { 292 item: TimeTable = { title: "", projects: [] } 293 header?: ComponentContent<HeadBuilderParams> = undefined 294 footer?: ComponentContent<FootBuilderParams> = undefined 295 headerParam = new HeadBuilderParams(this.item.title) 296 footerParam = new FootBuilderParams(this.item.projects.length) 297 298 aboutToAppear(): void { 299 this.header = new ComponentContent(this.getUIContext(), wrapBuilder(itemHead), this.headerParam) 300 this.footer = new ComponentContent(this.getUIContext(), wrapBuilder(itemFoot), this.footerParam) 301 } 302 GetHeader() { 303 this.header?.update(new HeadBuilderParams(this.item.title)); 304 return this.header; 305 } 306 307 GetFooter() { 308 this.footer?.update(new FootBuilderParams(this.item.projects.length)); 309 return this.footer; 310 } 311 312 build() { 313 ListItemGroup({ 314 headerComponent: this.GetHeader(), 315 footerComponent: this.GetFooter() 316 }) { 317 ForEach(this.item.projects, (project: string) => { 318 ListItem() { 319 Text(project) 320 .width("100%") 321 .height(100) 322 .fontSize(20) 323 .textAlign(TextAlign.Center) 324 } 325 }, (item: string) => item) 326 } 327 .divider({ strokeWidth: 1, color: Color.Blue }) // 每行之间的分界线 328 } 329} 330 331@Entry 332@Component 333struct ListItemGroupExample { 334 @State timeTable: TimeTable[] = [ 335 { 336 title: '星期一', 337 projects: ['语文', '数学', '英语'] 338 }, 339 { 340 title: '星期二', 341 projects: ['物理', '化学', '生物'] 342 }, 343 { 344 title: '星期三', 345 projects: ['历史', '地理', '政治', '体育'] 346 }, 347 { 348 title: '星期四', 349 projects: ['美术', '音乐'] 350 } 351 ] 352 353 build() { 354 Column() { 355 Button("update").width(100).height(50).onClick(() => { 356 this.timeTable[0] = { 357 title: '更新后的星期一', 358 projects: ['语文', '物理', '历史', '美术'] 359 } 360 }) 361 List({ space: 20 }) { 362 ForEach(this.timeTable, (item: TimeTable) => { 363 MyItemGroup({ item: item }) 364 }) 365 } 366 .layoutWeight(1) 367 .sticky(StickyStyle.Header | StickyStyle.Footer) 368 .scrollBar(BarState.Off) 369 } 370 .backgroundColor($r('sys.color.background_primary')) 371 } 372} 373``` 374 375
