第十节HarmonyOS 常用容器组件4-Grid与GridItem

1、描述

网格容器，由行和列分割的单元格所组成，通过指定“项目”所在的单元格做出各种各样的布局。

1. 子组件

包含GridItem子组件。

3、接口

Grid(scroller?: Scroller)

4、参数

参数名	参数类型	必填	描述
scroller	Scroller	否	可滚动组件的控制器。用于与可滚动组件进行绑定。

5、属性

名称	参数类型	描述
columnsTemplate	string	设置当前网格布局列的数量，不设置默认1列。 例如：‘1fr 1fr 2fr’是将父组件分3列，将父组件允许的宽分4等份，第一列占1份，第二例占1份，第三列占2份。 说明： 设置为‘0fr’时，该列的列宽为0，即不显示GridItem。设置为其它非法值时，GridItem显示为固定1列。
rowsTemplate	string	设置当前网格布局行的数量，不设置默认1行。 例如：‘1fr 1fr 2fr’是将父组件分3行，将父组件允许的高分4等份，第一行占1份，第二行占1份，第三行占2份。 说明： 设置为‘0fr’时，该列的行宽为0，即不显示GridItem。设置为其它非法值时，GridItem显示为固定1行处理。
columnsGap	length	设置列与列的间距。默认值0，设置为小于0的值时，按默认值显示。
rowsGap	length	设置行与行的间距，默认值0，设置为小于0的值时，按默认值显示。
scrollBar	BarState	设置滚动条状态。默认值：BarState.Off
scrollBarColor	String | number | Color	设置滚动条的颜色
scrollBarWidth	string | number	设置滚动条的宽度。宽度设置后，滚动条正常状态和按压状态宽度均为滚动条的宽度值。默认值：4vp
cachedCount	number	设置预加载的GridItem的数量，只在LazyForEach中生效。默认值：1。 说明：设置缓存后会在Grid显示区域上下各缓存cachedCount*列数个GridItem。LazyForEach超出显示和缓存范围的GridItem会被释放。
editMode	boolean	设置Grid是否进入编辑模式，进入编辑模式可以拖拽Grid组件内部GridItem。默认值：false。
layoutDirection	GridDirection	设置布局的主轴方向。默认值：GridDirection.Row。
maxCount	number	当layoutDriection是Row/RowReverse时，表示可显示的最大列数。当layoutDriection是Column/ColumnReverse时，表示可显示的最大行数。 默认值：Infinity。
minCount	number	当layoutDriection是Row/RowReverse时，表示可显示的最小列数。当layoutDriection是Column/ColumnReverse时，表示可显示的最小行数。 默认值：1。
cellLength	number	当layoutDirection是Row/RowReverse时，表示一行的高度。当layoutDirection是Column/ColumnReverse时，表示一列的宽度。 默认值：第一个元素的大小
multiSelectable	boolean	是否开启鼠标框选。 默认值：false。
supportAnimation	boolean	是否支持动画。当前支持GridItem拖拽动画。默认值：flase。

Grid组件根据rowsTemplate、columnsTemplate属性的设置情况，可分为以下三种布局模式：

1、rowsTemplate、columnsTemplate同时设置：

（1）、Grid只展示固定行列数的元素，其余元素不展示，且Grid不可滚动。

（2）、此模式下以下属性不生效：layoutDirection、maxCount、minCount、cellLength。

（3）、Grid的宽高没有设置时，默认适应父组件尺寸。

（4）、Gird网格列大小按照Gird自身内容区域大小减去所有行列Gap后按各个行列所占比重分配。

（5）、GridItem默认填满网格大小。

（6）、此模式下GridItem同时设置了rowStart、columnStart，会用设置的rowStart、columnStart所在位置摆放GridItem。如果这个位置已经有GridItem则会发生重叠。

（7）、如果GridItem设置了rowStart、columnStart其中一个，会从上一个GridItem布局位置开始遍历寻找满足rowStart或columnStart的空闲位置摆放，如果无满足条件的空闲位置，则不布局该GridItem。

（8）、如果GridItem的rowStart、columnStart属性都没有设置，会从上一个GridItem布局位置开始遍历寻找空闲位置摆放，如果没有空闲位置，则不布局该GridItem。

（9）、如果GridItem的rowEnd有设置，但是rowStart没有设置，当做rowStart已经设置，并且和rowEnd设置为相同值。如果GridItem的columnEnd有设置，但是columnStart没有设置，当做columnStart已经设置，并且和columnEnd设置为相同值。

2、rowsTemplate、columnsTemplate仅设置其中的一个：

（1）、元素按照设置的方向进行排布，超出Grid显示区域后，Grid可通过滚动的方式展示。

（2）、如果设置了columnsTemplate，Gird滚动方向为垂直方向，主轴方向为垂直方向，交叉轴方向为水平方向。

（3）、如果设置了rowsTemplate，Gird滚动方向为水平方向，主轴方向为水平方向，交叉轴方向为垂直方向。

（4）、此模式下以下属性不生效：layoutDirection、maxCount、minCount、cellLength。

（5）、网格交叉轴方向尺寸根据Gird自身内容区域交叉轴尺寸减去交叉轴方向所有Gap后按所占比重分配。

（6）、网格主轴方向尺寸取当前网格交叉轴方向所有GridItem高度最大值。

（7）、此模式下GridItem同时设置了rowStart、columnStart，会用设置的rowStart、columnStart所在位置摆放GridItem。如果这个位置已经有GridItem则会发生重叠。

（8）、如果GridItem设置了rowStart、columnStart其中一个，会从上一个GridItem布局位置开始遍历寻找满足rowStart或columnStart的空闲位置摆放。

（9）、如果GridItem的rowStart、columnStart属性都没有设置，会从上一个GridItem布局位置开始遍历寻找空闲位置摆放。

（10）、如果GridItem的rowEnd有设置，但是rowStart没有设置，当做rowStart已经设置，并且和rowEnd设置为相同值。如果GridItem的columnEnd有设置，但是columnStart没有设置，当做columnStart已经设置，并且和columnEnd设置为相同值。

3、rowsTemplate、columnsTemplate都不设置：

（1）、元素在layoutDirection方向上排布，列数由Grid的宽度、首个元素的宽度、minCount、maxCount、columnsGap共同决定。

（2）、行数由Grid高度、首个元素高度、cellLength、rowsGap共同决定。超出行列容纳范围的元素不显示，也不能通过滚动进行展示。

（3）、此模式下仅生效以下属性：layoutDirection、maxCount、minCount、cellLength、editMode、columnsGap、rowsGap。

（4）、当前layoutDirection设置为Row时，先从左到右排列，排满一行再排一下一列。剩余高度不足时不再布局，整体内容顶部居中。

（5）、当前layoutDirection设置为Column时，先从上到下排列，排满一列再排一下一列，剩余宽度度不足时不再。整体内容顶部居中。

（6）、此模式下GridItem的rowStart、columnStart不生效。

6、GridDriection枚举说明：

名称	描述
Row	主轴布局方向沿水平方向布局，即自左往右先填满一行，再去填下一行。
Column	主轴布局方向沿垂直方向布局，即自上往下先填满一列，再去填下一列。
RowReverse	主轴布局方向沿水平方向反向布局，即自右往左先填满一行，再去填下一行。
ColumnReverse	主轴布局方向沿垂直方向反向布局，即自下往上先填满一列，再去填下一列。

7、事件

名称	功能描述
onScrollIndex(event:(first:number) => void)	当前网格显示的起始位置Item发生变化时触发。first：当前显示的网格起始位置的索引。
onItemDragStart(event:(event: ItemDragInfo, itemIndex: number) => (0 => any) | void )	喀什拖动网格元素时触发。 - event: 见ItemDragInfo对象说明。 - itemIndex: 被拖拽网格元素索引值。 说明： 返回void表示不能拖拽。 手指长按GridItem时触发该事件。
onItemDragEnter(event: (event: ItemDragInfo) => void)	拖拽进入网格元素范围内时触发。 - event: 见ItemDragInfo对象说明。
onItemDragMove(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number) => void)	拖拽在网格元素范围内移动时触发。 - event: 见ItemDragInfo对象说明。 - itemIndex: 拖拽起始位置。 - insertIndex: 拖拽插入位置。
onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void)	拖拽离开网格元素时触发。 - event: 见ItemDragInfo对象说明。 - itemIndex: 拖拽离开的网格元素索引值。
onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void)	绑定该事件的网格元素可作为拖拽释放目标，当在网格元素内停止拖拽时触发。 - event: 见ItemDragInfo对象说明。 - itemIndex: 拖拽起始位置。 - insertIndex: 拖拽插入位置。 - isSuccess: 是否成功释放。

7.1、子组件GridItem

描述：网格布局中单项内容容器。

子组件：可以包含子组件。

接口：GridItem()

属性：

名称	参数类型	描述
rowStart	number	指定当前元素起始行号。
rowEnd	number	指定当前元素终点行号。
columnStart	number	指定当前元素起始列号。
columnEnd	number	指定当前元素终点列号。
forceRebuild(deprecated)	boolean	设置在触发组件build时是否重新创建此节点。 从API version9开始废弃。GridItem会根据自身属性和子组件变化自行决定是否需要重新创建，无需设置。 默认值：false
selectable8+	boolean	当前GridItem元素是否可以被鼠标框选。 > 说明： > 外层Grid容器的鼠标框选开启时，GridItem的框选才生效。 默认值：true

说明：

起始行号、终点行号、起始列号、终点列号生效规则如下：

（1）、rowStart/rowEnd合理取值范围为0~总行数-1，columnStart/columnEnd合理取值范围为0~总列数-1。

（2）、只有在设置columnTemplate和rowTemplate的Grid中，设置合理的rowStart/rowEnd/columnStart/columnEnd四个属性的GridItem才能按照指定的行列号布局。

（3）、在设置columnTemplate和rowTemplate的Grid中，单独设置行号rowStart/rowEnd或列号columnStart/columnEnd的GridItem会占用指定的行数(rowEnd-rowStart+1)或列数(columnEnd-colum nStart+1)。

（4）、在只设置columnTemplate的Grid中设置列号columnStart/columnEnd的GridItem按照指定的列数布局。

（5）、在只设置rowTemplate的Grid中设置行号rowStart/rowEnd的GridItem按照指定的行数布局。

（6）、columnTemplate和rowTemplate都不设置的Grid中GridItem的行列号属性无效。

事件：

名称：onSelect(event: (isSelected: boolean) => void)

功能描述：GridItem元素被鼠标框选的状态改变时触发回调。

isSelected：进入鼠标框选范围即被选中返回true， 移出鼠标框选范围即未被选中返回false。

8、示例

@Entry
@Component
struct GridPage {
  @State message: string = '网格容器，由行和列分割的单元格所组成，通过指定“项目”所在的单元格做出各种各样的布局。';
  @State gridList: String[] = ['0', '1', '2', '3', '4'];
  scroller: Scroller = new Scroller(); // 控制器

  build() {
    Column({ space: 5 }) {
      Grid() {
        ForEach(this.gridList, (day: string) => {
          ForEach(this.gridList, (day: string) => {
            GridItem() {
              Text(day)
                .fontSize(16)
                .backgroundColor(0xF9CF93)
                .width('100%')
                .height('100%')
                .textAlign(TextAlign.Center)
            }
          }, day => day)
        }, day => day)
      }
      .columnsTemplate('1fr 1fr 1fr 1fr 1fr')
      .rowsTemplate('1fr 1fr 1fr 1fr 1fr')
      .columnsGap(10)
      .rowsGap(10)
      .width('90%')
      .backgroundColor(0xFAEEE0)
      .height(300)

      Text('scroll').fontColor(0xCCCCCC).fontSize(9).width('90%')
      Grid(this.scroller) {
        ForEach(this.gridList, (day: string) => {
          ForEach(this.gridList, (day: string) => {
            GridItem() {
              Text(day)
                .fontSize(16)
                .backgroundColor(0xF9CF93)
                .width('100%')
                .height(80)
                .textAlign(TextAlign.Center)
            }
          }, day => day)
        }, day => day)
      }
      .columnsTemplate('1fr 1fr 1fr 1fr 1fr')
      .columnsGap(10)
      .rowsGap(10)
      .onScrollIndex((first: number) => {
        console.info(first.toString())
      })
      .width('90%')
      .backgroundColor(0xFAEEE0)
      .height(300)

      Button('next page')
        .onClick(() => { // 点击后滑到下一页
          this.scroller.scrollPage({ next: true })
        })

    }.width('100%').margin({ top: 5 })
  }
}

9、效果图