智能客服
你问我答,随时在线为你解决问题
栅格布局可以为布局提供规律性的结构,解决多尺寸多设备的动态布局问题,保证不同设备上各个模块的布局一致性。
栅格容器组件,仅可以和栅格子组件(GridCol)在栅格布局场景中使用。
支持根据设备尺寸和断点动态调整列数与间距,实现响应式布局。
该组件从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
可以包含GridCol子组件。
GridRow(option?: GridRowOptions)
栅格行布局容器。仅可以和栅格子组件在栅格布局场景中使用。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| option | GridRowOptions | 否 | 栅格行布局容器的布局选项。当需要自定义栅格布局(如设置列数、间距、断点位置、排列方向等)时传入此参数。不传入时使用默认配置。GridRow需与GridCol子组件配合使用。 |
设置栅格行布局容器的布局选项。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| columns | number | GridRowColumnOption | 否 | 是 | 设置布局列数。 取值为大于0的整数。 - API version 20之前:默认值为12。 - API version 20及之后:默认值为{ xs: 2, sm: 4, md: 8, lg: 12, xl: 12, xxl: 12 } 非法值:按默认值处理。 |
| gutter | Length | GutterOption | 否 | 是 | 栅格布局间距。 默认值:0vp 非法值:按默认值处理。 单位:vp |
| breakpoints | BreakPoints | 否 | 是 | 设置断点位置的单调递增数组,以及断点切换时的参照对象(基于应用窗口或容器尺寸)。 默认值: { value: ["320vp", "600vp", "840vp"], reference: BreakpointsReference.WindowSize } 非法值:按默认值处理。 单位:vp |
| direction | GridRowDirection | 否 | 是 | 栅格布局排列方向。支持Row(行方向排列,适用于常规LTR布局)和RowReverse(逆序行方向排列,适用于RTL布局或需要反向排列的场景)。 默认值:GridRowDirection.Row 非法值:按默认值处理。 |
栅格布局间距类型,用于描述栅格子组件不同方向的间距。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| x | Length | GridRowSizeOption | 否 | 是 | 栅格子组件水平方向间距。取值范围:大于等于0的数值或字符串。 默认值:0vp。 非法值:按默认值处理。 单位:vp |
| y | Length | GridRowSizeOption | 否 | 是 | 栅格子组件垂直方向间距。取值范围:大于等于0的数值或字符串。 默认值:0vp。 非法值:按默认值处理。 单位:vp |
栅格在不同宽度设备类型下的栅格列数配置。
API version 20之前,仅配置部分断点下GridRow组件的栅格列数,取已配置的相邻较小断点(如md的相邻较小断点为sm)的栅格列数补全未配置的栅格列数。若未配置相邻较小断点的栅格列数,以默认栅格列数12补全未配置的栅格列数。
- 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组件的栅格列数,取已配置的相邻较小断点的栅格列数补全未配置的栅格列数。若未配置相邻较小断点的栅格列数,取已配置的更大断点的栅格列数补全未配置的栅格列数。
- 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。 非法值:按默认值处理。 |
栅格在不同宽度设备类型下的gutter大小配置。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| xs | Length | 否 | 是 | 在最小宽度类型设备上,栅格子组件的间距。取值范围:大于等于0的数值或字符串。 默认值:0vp 单位:vp 非法值:按默认值处理。 |
| sm | Length | 否 | 是 | 在小宽度类型设备上,栅格子组件的间距。取值范围:大于等于0的数值或字符串。 默认值:0vp 单位:vp 非法值:按默认值处理。 |
| md | Length | 否 | 是 | 在中等宽度类型设备上,栅格子组件的间距。取值范围:大于等于0的数值或字符串。 默认值:0vp 单位:vp 非法值:按默认值处理。 |
| lg | Length | 否 | 是 | 在大宽度类型设备上,栅格子组件的间距。取值范围:大于等于0的数值或字符串。 默认值:0vp 单位:vp 非法值:按默认值处理。 |
| xl | Length | 否 | 是 | 在特大宽度类型设备上,栅格子组件的间距。取值范围:大于等于0的数值或字符串。 默认值:0vp 单位:vp 非法值:按默认值处理。 |
| xxl | Length | 否 | 是 | 在超大宽度类型设备上,栅格子组件的间距。取值范围:大于等于0的数值或字符串。 默认值:0vp 单位:vp 非法值:按默认值处理。 |
设置栅格容器组件的断点。更多断点的说明参考栅格容器断点。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| value | Array<string> | 否 | 是 | 设置断点位置的单调递增数组,字符串格式为"数字+vp",例如"320vp"、"600vp"等。 默认值:["320vp", "600vp", "840vp"] 非法值:按默认值处理。 单位:vp 默认断点适用于大多数场景,可根据特殊屏幕尺寸或特定布局需求自定义。 |
| reference | BreakpointsReference | 否 | 是 | 断点切换参照物。支持WindowSize(以窗口为参照)和ComponentSize(以容器为参照)。 默认值:BreakpointsReference.WindowSize 非法值:按默认值处理。 |
- // 启用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']}
设置栅格容器组件的断点参照物。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 值 | 说明 |
|---|---|---|
| WindowSize | 0 | 以窗口为参照。断点计算基于应用窗口尺寸,适用于需要根据窗口整体大小变化进行响应式布局的场景。 |
| ComponentSize | 1 | 以容器为参照。断点计算基于GridRow组件自身尺寸,适用于需要根据组件容器尺寸变化进行响应式布局的场景,例如GridRow嵌套在其他容器中时。 |
栅格元素排列方向。
栅格元素仅支持Row/RowReverse排列,不支持Column/ColumnReverse方向排列。
栅格子组件仅能通过span、offset计算子组件位置与大小。多个子组件span超过规定列数时自动换行。
单个元素span大小超过最大列数时后台默认span为最大列数。
新一行的offset加上子组件的span超过总列数时,将下一个子组件放在新一行。
例:Item1: GridCol({ span: 6 }), Item2: GridCol({ span: 8, offset:11 })。

卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 值 | 说明 |
|---|---|---|
| Row | 0 | 栅格元素按照行方向排列。适用于常规LTR(从左到右)布局场景。 |
| RowReverse | 1 | 栅格元素按照逆序行方向排列,适用于RTL(从右到左)语言布局或需要反向排列的场景。 |
除支持通用属性外,还支持以下属性:
alignItems(value: ItemAlign)
设置GridRow中的GridCol交叉轴方向对齐方式。GridCol本身也可通过alignSelf(ItemAlign)设置自身对齐方式。当上述两种对齐方式都设置时,以GridCol自身设置为准。
卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | ItemAlign | 是 | GridRow中的GridCol交叉轴方向对齐方式。 默认值:ItemAlign.Start 非法值:按默认值处理。 说明: ItemAlign支持的枚举:ItemAlign.Start、ItemAlign.Center、ItemAlign.End、ItemAlign.Stretch。 |
除支持通用事件外,还支持以下事件:
onBreakpointChange(callback: (breakpoints: string) => void)
断点发生变化时触发回调。回调函数接收到的breakpoints参数表示当前断点值(取值为"xs"、"sm"、"md"、"lg"、"xl"、"xxl"),开发者可在回调中根据断点值执行相应的UI布局调整或业务逻辑处理。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callback | (breakpoints: string) => void | 是 | 断点变化时触发的回调函数。参数breakpoints表示当前断点值,取值为"xs"、"sm"、"md"、"lg"、"xl"、"xxl"。 |
本示例展示GridRow组件的基本用法。
- // 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 })
- }
- }

本示例展示GridCol组件在不同alignItems对齐方式下的效果。
- @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%')
- }
- }
