!8741 add list item group documents

Merge pull request !8741 from yeyinglong/listitemgroup

zh-cn/application-dev/reference/arkui-ts/Readme-CN.md

@@ -104,6 +104,7 @@
     - [GridItem](ts-container-griditem.md)
     - [List](ts-container-list.md)
     - [ListItem](ts-container-listitem.md)
+    - [ListItemGroup](ts-container-listitemgroup.md)
     - [Navigator](ts-container-navigator.md)        
     - [Panel](ts-container-panel.md)
     - [Refresh](ts-container-refresh.md)

zh-cn/application-dev/reference/arkui-ts/ts-container-list.md

@@ -16,7 +16,7 @@
 
 ## 子组件
 
-包含[ListItem](ts-container-listitem.md)子组件。
+包含[ListItem](ts-container-listitem.md)、[ListItemGroup](ts-container-listitemgroup.md)子组件。
 
 
 ## 接口
@@ -44,8 +44,9 @@ List(value:{space?: number | string, initialIndex?: number, scroller?: Scroller}
 | restoreId<sup>8+</sup> | number | - | 组件迁移标识符，标识后的组件在应用迁移时，组件状态会被迁移到被拉起方的同标识组件。<br/>列表组件状态，包括起始位置显示的item序号。 |
 | lanes<sup>9+</sup> | number \|<br>{<br/>minLength: Length,<br/>maxLength: Length<br/>} | 1 | 以列模式为例（listDirection为Axis.Vertical）:<br/>lanes用于决定List组件在交叉轴方向按几列布局，规则如下：<br/>- lanes为指定的数量时，根据指定的数量与List组件的交叉轴宽度来决定每列的宽度；<br/>- lane设置了{minLength，maxLength}时，根据List组件的宽度自适应决定lanes数量（即列数），保证缩放过程中lane的宽度符合{minLength，maxLength}的限制。其中，minLength条件会被优先满足，即优先保证符合ListItem的宽度符合最小宽度限制。例如在列模式下，设置了{minLength: 40vp，maxLength: 60vp}，则当List组件宽度为70vp时，ListItem为一列，并且根据alignListItem属性做靠左、居中或者靠右布局；当List组件宽度变化至80vp时，符合两倍的minLength，则ListItem自适应为两列。 |
 | alignListItem<sup>9+</sup> | ListItemAlign | ListItemAlign.Center | List交叉轴方向宽度大于ListItem交叉轴宽度 * lanes时，ListItem在List交叉轴方向的布局方式，默认为居中。 |
+| sticky<sup>9+</sup> | StickyStyle | StickyStyle.None | 配合[ListItemGroup](ts-container-listitemgroup.md)组件使用，设置ListItemGroup中header和footer是否要吸顶或吸底，参见StickyStyle的枚举说明。|
 
-- ListItemAlign枚举说明
+- ListItemAlign<sup>9+</sup>枚举说明
 
   | 名称   | 描述                                   |
   | ------ | -------------------------------------- |
@@ -53,6 +54,15 @@ List(value:{space?: number | string, initialIndex?: number, scroller?: Scroller}
   | Center | ListItem在List中，交叉轴方向居中对齐。 |
   | End    | ListItem在List中，交叉轴方向尾部对齐。 |
 
+- StickyStyle<sup>9+</sup>枚举说明
+
+  | 名称   | 描述                                   |
+  | ------ | -------------------------------------- |
+  | None  | ListItemGroup的header不吸顶，footer不吸底。 |
+  | Header | ListItemGroup的header吸顶。 |
+  | Footer | ListItemGroup的footer吸底。 |
+
+  sticky属性可以设置为 StickyStyle.Header | StickyStyle.Footer 以同时支持header吸顶和footer吸底。
 
 ## 事件
 

zh-cn/application-dev/reference/arkui-ts/ts-container-listitemgroup.md

+# ListItemGroup
+
+该组件用来展示列表item分组，宽度默认充满[List](ts-container-list.md)组件，必须配合List组件来使用。
+
+> **说明：**
+>
+> 该组件从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
+
+## 权限列表
+
+无
+
+
+## 子组件
+
+包含[ListItem](ts-container-listitem.md)子组件。
+
+
+## 接口
+
+ListItemGroup(options?: {header?: CustomBuilder, footer?: CustomBuilder, space?: number | string}})
+
+**参数：**
+
+  | 参数名 | 参数类型 | 必填 | 参数描述 |
+  | -------- | -------- | -------- | -------- |
+  | header | [CustomBuilder](../../ui/ts-types.md#custombuilder8) | 否 |  设置ListItemGroup头部组件。 |
+  | footer | [CustomBuilder](../../ui/ts-types.md#custombuilder8) | 否 |  设置ListItemGroup尾部组件。 |
+  | space | number \| string | 否 | 列表项间距。 |
+
+## 属性
+
+| 名称 | 参数类型 |  描述 |
+| -------- | -------- | -------- |
+| divider | {<br/>strokeWidth:&nbsp;[Length](../../ui/ts-types.md#length),<br/>color?:&nbsp;[ResourceColor](../../ui/ts-types.md#resourcecolor8),<br/>startMargin?:&nbsp;[Length](../../ui/ts-types.md#length),<br/>endMargin?:&nbsp;[Length](../../ui/ts-types.md#length)<br/>}&nbsp;\|&nbsp;null | 用于设置ListItem分割线样式，默认无分割线。<br/>strokeWidth:&nbsp;分割线的线宽。<br/>color:&nbsp;分割线的颜色。<br/>startMargin：&nbsp;分割线距离列表侧边起始端的距离。<br/>endMargin:&nbsp;分割线距离列表侧边结束端的距离。 |
+
+
+## 示例
+
+```ts
+// xxx.ets
+function itemHeadBuilder(text: string) {
+  @Builder function itemHead() {
+    Text(text)
+      .fontSize(20)
+      .backgroundColor(0xAABBCC)
+      .width("100%")
+      .padding(10)
+  }
+  return itemHead
+}
+
+function itemFootBuilder(num: number) {
+  @Builder function itemFoot() {
+    Text('共' + num + "节课")
+      .fontSize(16)
+      .backgroundColor(0xAABBCC)
+      .width("100%")
+      .padding(5)
+  }
+  return itemFoot
+}
+
+@Entry
+@Component
+struct ListItemGroupExample {
+  private timetable: any = [
+    {
+      title:'星期一',
+      projects:['语文', '数学', '英语']
+    },
+    {
+      title:'星期二',
+      projects:['物理', '化学', '生物']
+    },
+    {
+      title:'星期三',
+      projects:['历史', '地理', '政治']
+    },
+    {
+      title:'星期四',
+      projects:['美术', '音乐', '体育']
+    }
+  ]
+
+  build() {
+    Column() {
+      List({ space: 20 }) {
+        ForEach(this.timetable, (item) => {
+          ListItemGroup({ header:itemHeadBuilder(item.title), footer:itemFootBuilder(item.projects.length) }) {
+            ForEach(item.projects, (project) => {
+              ListItem() {
+                Text(project)
+                  .width("100%").height(100).fontSize(20)
+                  .textAlign(TextAlign.Center).backgroundColor(0xFFFFFF)
+              }
+            }, item => item)
+          }
+          .borderRadius(20)
+          .divider({ strokeWidth: 1, color: 0xDCDCDC }) // 每行之间的分界线
+        })
+      }
+      .width('90%')
+      .sticky(StickyStyle.Header|StickyStyle.Footer)
+    }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 })
+  }
+}
+```
+
+![zh-cn_image_0000001219864159](figures/zh-cn_image_listitemgroup.gif)