# GridRow > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 栅格布局可以为布局提供规律性的结构，解决多尺寸多设备的动态布局问题，保证不同设备上各个模块的布局一致性。 栅格容器组件，仅可以和栅格子组件([GridCol](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-gridcol))在栅格布局场景中使用。 支持根据设备尺寸和断点动态调整列数与间距，实现响应式布局。 > 说明 > > 该组件从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 ## 子组件 可以包含GridCol子组件。 ## 接口 GridRow(option?: GridRowOptions) 栅格行布局容器。仅可以和栅格子组件在栅格布局场景中使用。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** |参数名|类型|必填|说明| |:-----|:------------------------------------|:-|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |option|[GridRowOptions](#gridrowoptions对象说明)|否|栅格行布局容器的布局选项。当需要自定义栅格布局（如设置列数、间距、断点位置、排列方向等）时传入此参数。不传入时使用默认配置。GridRow需与[GridCol](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-gridcol)子组件配合使用。| ## GridRowOptions对象说明 设置栅格行布局容器的布局选项。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full |名称|类型|只读|可选|说明| |:----------|:--------------------------------------------------------------------------------------------------------------------------|:-|:-|:-------------------------------------------------------------------------------------------------------------------------------------------------| |columns|number | [GridRowColumnOption](#gridrowcolumnoption)|否|是|设置布局列数。 取值为大于0的整数。 - API version 20之前：默认值为12。 - API version 20及之后：默认值为{ xs: 2, sm: 4, md: 8, lg: 12, xl: 12, xxl: 12 } 非法值：按默认值处理。| |gutter|[Length](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#length) | [GutterOption](#gutteroption)|否|是|栅格布局间距。 默认值：0vp 非法值：按默认值处理。 单位：vp| |breakpoints|[BreakPoints](#breakpoints)|否|是|设置断点位置的单调递增数组，以及断点切换时的参照对象（基于应用窗口或容器尺寸）。 默认值： { value: ["320vp", "600vp", "840vp"], reference: BreakpointsReference.WindowSize } 非法值：按默认值处理。 单位：vp| |direction|[GridRowDirection](#gridrowdirection枚举说明)|否|是|栅格布局排列方向。支持Row（行方向排列，适用于常规LTR布局）和RowReverse（逆序行方向排列，适用于RTL布局或需要反向排列的场景）。 默认值：GridRowDirection.Row 非法值：按默认值处理。| ## GutterOption 栅格布局间距类型，用于描述栅格子组件不同方向的间距。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full |名称|类型|只读|可选|说明| |:-|:------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:--------------------------------------------------------| |x|[Length](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#length) | [GridRowSizeOption](#gridrowsizeoption)|否|是|栅格子组件水平方向间距。取值范围：大于等于0的数值或字符串。 默认值：0vp。 非法值：按默认值处理。 单位：vp| |y|[Length](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#length) | [GridRowSizeOption](#gridrowsizeoption)|否|是|栅格子组件垂直方向间距。取值范围：大于等于0的数值或字符串。 默认值：0vp。 非法值：按默认值处理。 单位：vp| ## GridRowColumnOption 栅格在不同宽度设备类型下的栅格列数配置。 API version 20之前，仅配置部分断点下GridRow组件的栅格列数，取已配置的相邻较小断点（如md的相邻较小断点为sm）的栅格列数补全未配置的栅格列数。若未配置相邻较小断点的栅格列数，以默认栅格列数12补全未配置的栅格列数。 ```ts columns: {xs:2, md:4, lg:8} // 等于配置 columns: {xs:2, sm:2, md:4, lg:8, xl:8, xxl:8} columns: {md:4, lg:8} // 等于配置 columns: {xs:12, sm:12, md:4, lg:8, xl:8, xxl:8} ``` API version 20及以后，仅配置部分断点下GridRow组件的栅格列数，取已配置的相邻较小断点的栅格列数补全未配置的栅格列数。若未配置相邻较小断点的栅格列数，取已配置的更大断点的栅格列数补全未配置的栅格列数。 ```ts columns: {xs:2, md:4, lg:8} // 等于配置 columns: {xs:2, sm:2, md:4, lg:8, xl:8, xxl:8} columns: {md:4, lg:8} // 等于配置 columns: {xs:4, sm:4, md:4, lg:8, xl:8, xxl:8} ``` 建议手动配置不同断点下GridRow组件的栅格列数，避免默认补全的栅格列数的布局效果不符合预期。 每列栅格的宽度为GridRow的内容区大小减去栅格子组件的间距gutter，再除以总的栅格列数。比如，宽800vp的GridRow设置columns为12，gutter设置为10vp，padding设置为20vp，那么每列栅格的宽度为(800 - 20 * 2 - 10 * 11) / 12。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full |名称|类型|只读|可选|说明| |:--|:-----|:-|:-|:---------------------------------------------------------------------------------------------------| |xs|number|否|是|在最小宽度类型设备上，栅格容器组件的栅格列数。取值为大于0的整数。 - API version 20之前：默认值为12。 - API version 20及之后：默认值为2。 非法值：按默认值处理。| |sm|number|否|是|在小宽度类型设备上，栅格容器组件的栅格列数。取值为大于0的整数。 - API version 20之前：默认值为12。 - API version 20及之后：默认值为4。 非法值：按默认值处理。| |md|number|否|是|在中等宽度类型设备上，栅格容器组件的栅格列数。取值为大于0的整数。 - API version 20之前：默认值为12。 - API version 20及之后：默认值为8。 非法值：按默认值处理。| |lg|number|否|是|在大宽度类型设备上，栅格容器组件的栅格列数。取值为大于0的整数。 - API version 20之前：默认值为12。 - API version 20及之后：默认值为12。 非法值：按默认值处理。| |xl|number|否|是|在特大宽度类型设备上，栅格容器组件的栅格列数。取值为大于0的整数。 - API version 20之前：默认值为12。 - API version 20及之后：默认值为12。 非法值：按默认值处理。| |xxl|number|否|是|在超大宽度类型设备上，栅格容器组件的栅格列数。取值为大于0的整数。 - API version 20之前：默认值为12。 - API version 20及之后：默认值为12。 非法值：按默认值处理。| ## GridRowSizeOption 栅格在不同宽度设备类型下的gutter大小配置。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full |名称|类型|只读|可选|说明| |:--|:------------------------------------------------------------------------------------------|:-|:-|:---------------------------------------------------------------| |xs|[Length](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#length)|否|是|在最小宽度类型设备上，栅格子组件的间距。取值范围：大于等于0的数值或字符串。 默认值：0vp 单位：vp 非法值：按默认值处理。| |sm|[Length](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#length)|否|是|在小宽度类型设备上，栅格子组件的间距。取值范围：大于等于0的数值或字符串。 默认值：0vp 单位：vp 非法值：按默认值处理。| |md|[Length](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#length)|否|是|在中等宽度类型设备上，栅格子组件的间距。取值范围：大于等于0的数值或字符串。 默认值：0vp 单位：vp 非法值：按默认值处理。| |lg|[Length](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#length)|否|是|在大宽度类型设备上，栅格子组件的间距。取值范围：大于等于0的数值或字符串。 默认值：0vp 单位：vp 非法值：按默认值处理。| |xl|[Length](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#length)|否|是|在特大宽度类型设备上，栅格子组件的间距。取值范围：大于等于0的数值或字符串。 默认值：0vp 单位：vp 非法值：按默认值处理。| |xxl|[Length](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#length)|否|是|在超大宽度类型设备上，栅格子组件的间距。取值范围：大于等于0的数值或字符串。 默认值：0vp 单位：vp 非法值：按默认值处理。| ## BreakPoints 设置栅格容器组件的断点。更多断点的说明参考[栅格容器断点](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-layout-development-grid-layout#栅格容器断点)。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full |名称|类型|只读|可选|说明| |:--------|:------------------------------------------------|:-|:-|:----------------------------------------------------------------------------------------------------------------------------------| |value|Array|否|是|设置断点位置的单调递增数组，字符串格式为"数字+vp"，例如"320vp"、"600vp"等。 默认值：["320vp", "600vp", "840vp"] 非法值：按默认值处理。 单位：vp 默认断点适用于大多数场景，可根据特殊屏幕尺寸或特定布局需求自定义。| |reference|[BreakpointsReference](#breakpointsreference枚举说明)|否|是|断点切换参照物。支持WindowSize（以窗口为参照）和ComponentSize（以容器为参照）。 默认值：BreakpointsReference.WindowSize 非法值：按默认值处理。| ```ts // 启用xs、sm、md共3个断点 breakpoints: {value: ['100vp', '200vp']} // 启用xs、sm、md、lg共4个断点，断点范围值必须单调递增 breakpoints: {value: ['320vp', '600vp', '840vp']} // 启用xs、sm、md、lg、xl共5个断点，断点范围数量不可超过断点可取值数量-1 breakpoints: {value: ['320vp', '600vp', '840vp', '1080vp']} ``` ## BreakpointsReference枚举说明 设置栅格容器组件的断点参照物。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full |名称|值|说明| |:------------|:-|:-----------------------------------------------------------------------| |WindowSize|0|以窗口为参照。断点计算基于应用窗口尺寸，适用于需要根据窗口整体大小变化进行响应式布局的场景。| |ComponentSize|1|以容器为参照。断点计算基于GridRow组件自身尺寸，适用于需要根据组件容器尺寸变化进行响应式布局的场景，例如GridRow嵌套在其他容器中时。| ## GridRowDirection枚举说明 栅格元素排列方向。 > 说明 > > * 栅格元素仅支持Row/RowReverse排列，不支持Column/ColumnReverse方向排列。 > > * 栅格子组件仅能通过span、offset计算子组件位置与大小。多个子组件span超过规定列数时自动换行。 > > * 单个元素span大小超过最大列数时后台默认span为最大列数。 > > * 新一行的offset加上子组件的span超过总列数时，将下一个子组件放在新一行。 > > * 例：Item1: GridCol({ span: 6 })， Item2: GridCol({ span: 8, offset:11 })。 > > ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/fd/v3/DKPvN8v4QQuuupsVAZ5Lmg/zh-cn_image_0000002749334572.png?HW-CC-KV=V1&HW-CC-Date=20260929T121734Z&HW-CC-Expire=31536000000&HW-CC-Sign=C5CF983CDEA9404ED7814BFA4C17D1AAA4F6D13D4985B22C1B8A2EE36E71AF03) **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full |名称|值|说明| |:---------|:-|:----------------------------------------| |Row|0|栅格元素按照行方向排列。适用于常规LTR（从左到右）布局场景。| |RowReverse|1|栅格元素按照逆序行方向排列，适用于RTL（从右到左）语言布局或需要反向排列的场景。| ## 属性 除支持[通用属性](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-component-general-attributes)外，还支持以下属性： ### alignItems^10+^ alignItems(value: ItemAlign) 设置GridRow中的GridCol交叉轴方向对齐方式。GridCol本身也可通过alignSelf([ItemAlign](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-appendix-enums#itemalign))设置自身对齐方式。当上述两种对齐方式都设置时，以GridCol自身设置为准。 **卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 **模型约束：** 此接口仅可在Stage模型下使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** |参数名|类型|必填|说明| |:----|:---------------------------------------------------------------------------------------------------------|:-|:--------------------------------------------------------------------------------------------------------------------------------------------------| |value|[ItemAlign](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-appendix-enums#itemalign)|是|GridRow中的GridCol交叉轴方向对齐方式。 默认值：ItemAlign.Start 非法值：按默认值处理。 **说明：** ItemAlign支持的枚举：ItemAlign.Start、ItemAlign.Center、ItemAlign.End、ItemAlign.Stretch。| ## 事件 除支持[通用事件](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-component-general-events)外，还支持以下事件： ### onBreakpointChange onBreakpointChange(callback: (breakpoints: string) => void) 断点发生变化时触发回调。回调函数接收到的breakpoints参数表示当前断点值（取值为"xs"、"sm"、"md"、"lg"、"xl"、"xxl"），开发者可在回调中根据断点值执行相应的UI布局调整或业务逻辑处理。 > 说明 > > * 当[断点参照物](#breakpointsreference枚举说明)设置为BreakpointsReference.ComponentSize时，不要在onBreakpointChange回调中动态修改GridRow组件的[padding](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-size#padding)或[margin](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-size#margin)属性值，否则可能导致组件尺寸计算循环触发、布局抖动或渲染性能下降。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** |参数名|类型|必填|说明| |:-------|:----------------------------|:-|:-------------------------------------------------------------------| |callback|(breakpoints: string) => void|是|断点变化时触发的回调函数。参数breakpoints表示当前断点值，取值为"xs"、"sm"、"md"、"lg"、"xl"、"xxl"。| ## 示例 ### 示例1（栅格布局的基本用法） 本示例展示GridRow组件的基本用法。 ```ts // xxx.ets @Entry @Component struct GridRowExample { @State bgColors: Color[] = [Color.Red, Color.Orange, Color.Yellow, Color.Green, Color.Pink, Color.Grey, Color.Blue, Color.Brown] @State currentBp: string = 'unknown' build() { Column() { GridRow({ columns: 5, gutter: { x: 5, y: 10 }, breakpoints: { value: ['400vp', '600vp', '800vp'], reference: BreakpointsReference.WindowSize }, direction: GridRowDirection.Row }) { ForEach(this.bgColors, (color: Color) => { GridCol({ span: { xs: 1, sm: 2, md: 3, lg: 4 }, offset: 0, order: 0 }) { Row().width('100%').height('20vp') }.borderColor(color).borderWidth(2) }) }.width('100%').height('100%') .onBreakpointChange((breakpoint) => { this.currentBp = breakpoint }) }.width('80%').margin({ left: 10, top: 5, bottom: 5 }).height(200) .border({ color: '#880606', width: 2 }) } } ``` ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/97/v3/oAC7rMJtTS62sWRjyC42jw/zh-cn_image_0000002749494458.png?HW-CC-KV=V1&HW-CC-Date=20260929T121734Z&HW-CC-Expire=31536000000&HW-CC-Sign=1467833F75F36EC1D1924213A977CAED0C55DCCF1FFD0CA7587F71A7D2E470C1) ### 示例2（AlignItems的基本用法） 本示例展示GridCol组件在不同alignItems对齐方式下的效果。 ```ts @ComponentV2 struct AlignItemsDemo { bgColors: Color[] = [Color.Red, Color.Orange, Color.Yellow, Color.Green, Color.Pink]; @Param alignment: ItemAlign = ItemAlign.Start; // 接收父组件传入的alignItems属性值 ToString(alignment: ItemAlign): string { switch (alignment) { case ItemAlign.Start: return 'ItemAlign.Start'; case ItemAlign.Center: return 'ItemAlign.Center'; case ItemAlign.End: return 'ItemAlign.End'; case ItemAlign.Stretch: return 'ItemAlign.Stretch'; default: return 'ItemAlign.Auto'; } } build() { Column() { Text(this.ToString(this.alignment)) .fontSize(9) .fontColor(0xCCCCCC) .width('90%') .alignSelf(ItemAlign.Start) GridRow({ columns: 5, gutter: { x: 5, y: 10 }, }) { ForEach(this.bgColors, (color: Color, index: number) => { GridCol({ span: 1 }) { Row() { }.width('100%').height(`${(index + 1) * 20}%`) // GridCol内的Row设置不同的高度，方便观察alignItems属性的效果 }.borderColor(color).borderWidth(2) }) } .border({ color: '#880606', width: 2 }) .alignItems(this.alignment) .width('100%') } .height('20%') } } @Entry @ComponentV2 struct GridRowExample { alignmentArray: ItemAlign[] = [ItemAlign.Start, ItemAlign.Center, ItemAlign.End, ItemAlign.Stretch]; build() { Column({ space: 15 }) { ForEach(this.alignmentArray, (ele: ItemAlign) => { AlignItemsDemo({ alignment: ele }) }) }.width('80%').margin({ left: 10, top: 5, bottom: 5 }).height('100%') } } ``` ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/8d/v3/IvhOU_1lRQ28KjTDMRumTw/zh-cn_image_0000002779093515.png?HW-CC-KV=V1&HW-CC-Date=20260929T121734Z&HW-CC-Expire=31536000000&HW-CC-Sign=5144CF371C07F9409A625C09741CB40593CB008092CB64AAD4B98EA33D6C78E4)