鸿蒙ArkUI Grid和GridItem栅格容器组件的用法(附带示例)
Grid 作为栅格容器组件,由“行”和“列”分割的单元格组成,通过指定“项目”所在的单元格来做出各种各样的布局。GridItem 是栅格容器中单项内容容器。
Grid 通过配置对应的属性来控制其展示方式,主要的属性说明如下:
同理,GridItem 也是通过配置对应的属性来控制其展示方式的。GridItem 包含的属性说明如下:
说明:
Grid 和 GridItem 的示例代码如下:

图 1 Grid和GridItem的示例效果
Grid 通过配置对应的属性来控制其展示方式,主要的属性说明如下:
属性名称 | 类型 | 描述 |
---|---|---|
regularSize | [number, number] | 大小规则的 GridItem 在 Grid 中占的行数和列数,只支持占 1 行 1 列,即 [1, 1]。 |
irregularIndexes | number[] | 指定的 GridItem 索引在 Grid 中的大小是不规则的。当不设置 onGetIrregularSizeByIndex 时,irregularIndexes 中 GridItem 的默认大小为垂直滚动 Grid 的一整行或水平滚动 Grid 的一整列。 |
onGetIrregularSizeByIndex | (index: number) => [number, number] | 配合 irregularIndexes 使用,设置大小不规则的 GridItem 占用的行数和列数。 |
onGetRectByIndex | (index: number) => [number, number, number, number] | 设置指定索引 index 对应的 GridItem 的位置及大小 [rowStart, columnStart, rowSpan, columnSpan]。 |
columnsTemplate | string | 设置当前栅格布局列的数量或最小列宽值。 |
rowsTemplate | string | 设置当前栅格布局行的数量或最小行高值。 |
columnsGap | Length | 设置列与列的间距。 |
rowsGap | Length | 设置行与行的间距。 |
scrollBar | BarState | 设置滚动条状态。 |
scrollBarColor | string | number | Color | 设置滚动条的颜色。 |
scrollBarWidth | string | number | 设置滚动条的宽度。 |
cachedCount | number | 设置预加载的 GridItem 的数量。 |
editMode | boolean | 设置 Grid 是否进入编辑模式。 |
layoutDirection | GridDirection | 设置布局的主轴方向。 |
maxCount | number | 设置可显示的最大列数或行数。 |
minCount | number | 设置可显示的最小列数或行数。 |
cellLength | number | 设置一行的高度或一列的宽度。 |
multiSelectable | boolean | 是否开启鼠标框选。 |
supportAnimation | boolean | 是否支持动画。 |
edgeEffect | value: EdgeEffect, options?: EdgeEffectOptions | 设置边缘滑动效果。 |
enableScrollInteraction | boolean | 设置是否支持滚动手势。 |
nestedScroll | NestedScrollOptions | 设置嵌套滚动选项。 |
friction | number | Resource | 设置摩擦系数。 |
同理,GridItem 也是通过配置对应的属性来控制其展示方式的。GridItem 包含的属性说明如下:
属性名称 | 类型 | 描述 |
---|---|---|
rowStart | number | 指定当前元素起始行号。 |
rowEnd | number | 指定当前元素终点行号。 |
columnStart | number | 指定当前元素起始列号。 |
columnEnd | number | 指定当前元素终点列号。 |
selectable | boolean | 当前 GridItem 元素是否可以被鼠标框选。外层 Grid 容器的鼠标框选开启时,GridItem 的框选才生效。默认值:true。 |
selected | boolean | 设置当前 GridItem 选中状态。该属性支持双向绑定变量。该属性需要在设置选中态样式前使用,才能使选中态样式生效。默认值:false。 |
说明:
- rowStart、rowEnd、columnStart、columnEnd 属性用于定义 GridItem 在 Grid 中的位置和大小。
- selectable 属性用于控制 GridItem 是否可以被鼠标框选,依赖于外层 Grid 容器的框选设置。
- selected 属性用于设置 GridItem 的选中状态,并支持双向绑定,需要在使用前设置选中态样式。
Grid 和 GridItem 的示例代码如下:
Column() { Grid(this.scroller) { ForEach(this.numbers, (day: string) => { ForEach(this.numbers, (day: string) => { GridItem() { Text(day) .fontSize(16) .backgroundColor(0xF9CF93) .width('100%') .height(80) .textAlign(TextAlign.Center) } }, (day: string) => day) }, (day: string) => day) .columnsTemplate('1fr 1fr 1fr 1fr 1fr') .columnsGap(10) .rowsGap(10) .friction(0.6) .enableScrollInteraction(true) .supportAnimation(false) .multiSelectable(false) .edgeEffect(EdgeEffect.Spring) .scrollBar(BarState.On) .scrollBarColor(Color.Grey) .scrollBarWidth(4) .width('90%') .backgroundColor(0xFAEEE0) .height(300) .onScrollIndex((first: number, last: number) => { /** * 当前栅格显示的起始位置/终止位置的item发生变化时触发。栅格初始化时会触发一次 * first:当前显示的栅格起始位置的索引值 * last:当前显示的栅格终止位置的索引值 * Grid显示区域上第一个子组件/最后一个组件的索引值有变化就会触发 **/ console.info(first.toString()) console.info(last.toString()) }) .onScrollBarUpdate((index: number, offset: number) => { /** * 当前栅格显示的起始位置item发生变化时触发,可通过该回调设置滚动条的位置及长度 * index:当前显示的栅格起始位置的索引值 * offset:当前显示的栅格起始位置元素相对栅格显示起始位置的偏移,单位为vp **/ return { totalOffset: (index / 5) * (80 + 10) - offset, totalLength: 80 * 5 + 10 * 4 } }) .onScroll((scrollOffset: number, scrollState: ScrollState) => { /** * 栅格滑动时触发 * scrollOffset:每帧滚动的偏移量,Grid的内容向上滚动时偏移量为正,向下滚动时偏移量为负,单位为vp * scrollState:当前滑动状态 **/ console.info(scrollOffset.toString()) console.info(scrollState.toString()) }) .onScrollStart(() => { /** * 栅格滑动开始时触发。手指拖动栅格或栅格的滚动条触发的滑动开始时,会触发该事件 **/ console.info("xxx" + "Grid onScrollStart") }) .onScrollStop(() => { /** * 栅格滑动停止时触发。手指离开屏幕并且滑动停止时会触发该事件 **/ console.info("xxx" + "Grid onScrollStop") }) .onReachStart(() => { /** * 栅格到达起始位置时触发 **/ this.gridPosition = 0 console.info("xxx" + "Grid onReachStart") }) .onReachEnd(() => { /** * 栅格到达末尾位置时触发 **/ this.gridPosition = 2 console.info("xxx" + "Grid onReachEnd") }) }上述示例代码效果如下图所示:

图 1 Grid和GridItem的示例效果