鸿蒙5.0版开发：ArkTS容器组件（Grid）

往期鸿蒙全套实战文章必看：

• 鸿蒙开发核心知识点，看这篇文章就够了

• 最新版！鸿蒙HarmonyOS Next应用开发实战学习路线

• 鸿蒙HarmonyOS NEXT开发技术最全学习路线指南

• 鸿蒙应用开发实战项目，看这一篇文章就够了（部分项目附源码）

---

Grid

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

说明：

该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

仅支持GridItem子组件。

说明：

Grid子组件的索引值计算规则：

按子组件的顺序依次递增。

if/else语句中，只有条件成立分支内的子组件会参与索引值计算，条件不成立分支内的子组件不计算索引值。

ForEach/LazyForEach语句中，会计算展开所有子节点索引值。

if/else、ForEach和LazyForEach发生变化以后，会更新子节点索引值。

Grid子组件的visibility属性设置为Hidden或None时依然会计算索引值。

Grid子组件的visibility属性设置为None时不显示，但依然会占用子组件对应的网格。

Grid子组件设置position属性，会占用子组件对应的网格，子组件将显示在相对Grid左上角偏移position的位置。该子组件不会随其对应网格滚动，在对应网格滑出Grid显示范围外后不显示。

当Grid子组件之间留有空隙时，会根据当前的展示区域尽可能填补空隙，因此GridItem可能会随着网格滚动而改变相对位置。

接口

Grid(scroller?: Scroller, layoutOptions?: GridLayoutOptions)

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	参数类型	必填	参数描述
scroller	Scroller	否	可滚动组件的控制器。用于与可滚动组件进行绑定。 说明： 不允许和其他滚动类组件，如：List、Grid、Scroll等绑定同一个滚动控制对象。
layoutOptions10+	GridLayoutOptions	否	滚动Grid布局选项。

GridLayoutOptions10+

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

布局选项。其中,irregularIndexes和onGetIrregularSizeByIndex可对仅设置rowsTemplate或columnsTemplate的Grid使用，可以指定一个index数组，并为其中的index对应的GridItem设置其占据的行数与列数，使用方法参见示例3；onGetRectByIndex可对同时设置rowsTemplate和columnsTemplate的Grid使用，为指定的index对应的GridItem设置位置和大小，使用方法参见示例1。

参数：

名称	类型	必填	描述
regularSize	[number, number]	是	大小规则的GridItem在Grid中占的行数和列数，只支持占1行1列即[1, 1]。 原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。
irregularIndexes	number[]	否	指定的GridItem索引在Grid中的大小是不规则的。当不设置onGetIrregularSizeByIndex时，irregularIndexes中GridItem的默认大小为垂直滚动Grid的一整行或水平滚动Grid的一整列。 原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。
onGetIrregularSizeByIndex	(index: number) => [number, number]	否	配合irregularIndexes使用，设置不规则GridItem占用的行数和列数。开发者可为irregularIndexes中指明的index对应的GridItem设置占用的行数和列数。在API version 12之前，垂直滚动Grid不支持GridItem占多行，水平滚动Grid不支持GridItem占多列。 原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。
onGetRectByIndex11+	(index: number) => [number, number,number,number]	否	设置指定索引index对应的GridItem的位置及大小[rowStart,columnStart,rowSpan,columnSpan]。 其中rowStart为行起始位置，columnStart为列起始位置，无单位。 rowSpan为GridItem占用的行数，columnSpan为GridItem占用的列数，无单位。 rowStart和columnStart取大于等于0的自然数，若取负数时，rowStart和columnStart默认为0。 rowSpan和columnSpan取大于等于1的自然数，若取小数则向下取整，若小于1则按1计算。 说明： 第一种情况：某个GridItem发现给它指定的起始位置被占据了，则从起始位置[0,0]开始按顺序从左到右，从上到下寻找起始的放置位置。 第二种情况：如果起始位置没有被占据，但其他位置被占据了，无法显示全部的GridItem大小，则只会布局一部分。 原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

属性

除支持通用属性外，还支持以下属性：

columnsTemplate

columnsTemplate(value: string)

设置当前网格布局列的数量或最小列宽值，不设置时默认1列。

例如, ‘1fr 1fr 2fr’ 是将父组件分3列，将父组件允许的宽分为4等份，第一列占1份，第二列占1份，第三列占2份。

columnsTemplate(‘repeat(auto-fit, track-size)’)是设置最小列宽值为track-size，自动计算列数和实际列宽。

columnsTemplate(‘repeat(auto-fill, track-size)’)是设置固定列宽值为track-size，自动计算列数。其中repeat、auto-fit、auto-fill为关键字。track-size为列宽，支持的单位包括px、vp、%或有效数字，默认单位为vp，track-size至少包括一个有效列宽。

设置为’0fr’时，该列的列宽为0，不显示GridItem。设置为其他非法值时，GridItem显示为固定1列。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	string	是	当前网格布局列的数量或最小列宽值。

rowsTemplate

rowsTemplate(value: string)

设置当前网格布局行的数量或最小行高值，不设置时默认1行。

例如, '1fr 1fr 2fr’是将父组件分3行，将父组件允许的高分为4等份，第一行占1份，第二行占一份，第三行占2份。

rowsTemplate(‘repeat(auto-fit, track-size)’)是设置最小行高值为track-size，自动计算行数和实际行高。

rowsTemplate(‘repeat(auto-fill, track-size)’)是设置固定行高值为track-size，自动计算行数。其中repeat、auto-fit、auto-fill为关键字。track-size为行高，支持的单位包括px、vp、%或有效数字，默认单位为vp，track-size至少包括一个有效行高。

设置为’0fr’，则这一行的行宽为0，这一行GridItem不显示。设置为其他非法值，按固定1行处理。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	string	是	当前网格布局行的数量或最小行高值。

说明：

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

1、rowsTemplate、columnsTemplate同时设置：

• Grid只展示固定行列数的元素，其余元素不展示，且Grid不可滚动。
• 此模式下以下属性不生效：layoutDirection、maxCount、minCount、cellLength。
• Grid的宽高没有设置时，默认适应父组件尺寸。
• Grid网格列大小按照Grid自身内容区域大小减去所有行列Gap后按各个行列所占比重分配。
• GridItem默认填满网格大小。

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

• 元素按照设置的方向进行排布，超出Grid显示区域后，Grid可通过滚动的方式展示。
• 如果设置了columnsTemplate，Grid滚动方向为垂直方向，主轴方向为垂直方向，交叉轴方向为水平方向。
• 如果设置了rowsTemplate，Grid滚动方向为水平方向，主轴方向为水平方向，交叉轴方向为垂直方向。
• 此模式下以下属性不生效：layoutDirection、maxCount、minCount、cellLength。
• 网格交叉轴方向尺寸根据Grid自身内容区域交叉轴尺寸减去交叉轴方向所有Gap后按所占比重分配。
• 网格主轴方向尺寸取当前网格交叉轴方向所有GridItem高度最大值。

3、rowsTemplate、columnsTemplate都不设置：

• 元素在layoutDirection方向上排布，列数由Grid的宽度、首个元素的宽度、minCount、maxCount、columnsGap共同决定。
• 行数由Grid高度、首个元素高度、cellLength、rowsGap共同决定。超出行列容纳范围的元素