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