1# GridRow
2
3栅格布局可以为布局提供规律性的结构，解决多尺寸多设备的动态布局问题，保证不同设备上各个模块的布局一致性。
4
5栅格容器组件，仅可以和栅格子组件([GridCol](ts-container-gridcol.md))在栅格布局场景中使用。
6
7>  **说明：**
8>
9> 该组件从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
10
11
12## 子组件
13
14可以包含GridCol子组件。
15
16
17## 接口
18GridRow(option?: GridRowOptions)
19
20**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
21
22**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
23
24**系统能力：** SystemCapability.ArkUI.ArkUI.Full
25
26**参数：**
27| 参数名 |类型|必填|说明|
28|-----|-----|----|----|
29| option | [GridRowOptions](#gridrowoptions对象说明) | 否  | 栅格布局子组件参数。 |
30
31## GridRowOptions对象说明
32
33**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
34
35**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
36
37**系统能力：** SystemCapability.ArkUI.ArkUI.Full
38
39| 名称 |类型|必填|说明|
40|-----|-----|----|----|
41|columns| number \| [GridRowColumnOption](#gridrowcolumnoption) |  否  |设置布局列数。<br />默认值：12 |
42|gutter|[Length](ts-types.md#length) \| [GutterOption](#gutteroption)|   否  |栅格布局间距。<br />默认值：0 |
43|breakpoints|[BreakPoints](#breakpoints)|  否  |设置断点值的断点数列以及基于窗口或容器尺寸的相应参照。<br />默认值：<br />{<br />value: ["320vp", "600vp", "840vp"],<br />reference: BreakpointsReference.WindowSize<br />} |
44|direction|[GridRowDirection](#gridrowdirection枚举说明)|   否  |栅格布局排列方向。<br />默认值：GridRowDirection.Row |
45
46## GutterOption
47
48栅格布局间距类型，用于描述栅格子组件不同方向的间距。
49
50**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
51
52**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
53
54**系统能力：** SystemCapability.ArkUI.ArkUI.Full
55
56| 名称   | 类型   | 必填   | 说明                                     |
57| ----- | ------ | ---- | ---------------------------------------- |
58| x  | [Length](ts-types.md#length) \| [GridRowSizeOption](#gridrowsizeoption) | 否   | 栅格子组件水平方向间距。    |
59| y  | [Length](ts-types.md#length) \| [GridRowSizeOption](#gridrowsizeoption) | 否   | 栅格子组件竖直方向间距。    |
60
61## GridRowColumnOption
62
63栅格在不同宽度设备类型下，栅格列数。
64
65**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
66
67**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
68
69**系统能力：** SystemCapability.ArkUI.ArkUI.Full
70
71| 名称   | 类型   | 必填   | 说明                                     |
72| ----- | ------ | ---- | ---------------------------------------- |
73| xs  | number | 否    | 在栅格大小为xs的设备上，栅格容器组件的栅格列数。    |
74| sm  | number | 否    | 在栅格大小为sm的设备上，栅格容器组件的栅格列数。      |
75| md  | number | 否    | 在栅格大小为md的设备上，栅格容器组件的栅格列数。    |
76| lg  | number | 否    | 在栅格大小为lg的设备上，栅格容器组件的栅格列数。      |
77| xl  | number | 否    | 在栅格大小为xl的设备上，栅格容器组件的栅格列数。    |
78| xxl | number | 否    | 在栅格大小为xxl的设备上，栅格容器组件的栅格列数。    |
79
80**说明：**
81
82在GridRow栅格组件中，允许开发者使用breakpoints自定义修改[断点](../../../ui/arkts-layout-development-grid-layout.md#栅格系统断点)的取值范围，最多支持xs、sm、md、lg、xl、xxl六个断点，且名称不可修改。假设传入的数组是[n0, n1, n2, n3, n4]，各个断点取值如下：
83|断点|取值范围|
84|---|-----------|
85|xs |[0, n0)    |
86|sm |[n0, n1)   |
87|md |[n1, n2)   |
88|lg |[n2, n3)   |
89|xl |[n3, n4)   |
90|xxl|[n4, INF)  |
91
92## GridRowSizeOption
93
94栅格在不同宽度设备类型下，gutter的大小。
95
96**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
97
98**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
99
100**系统能力：** SystemCapability.ArkUI.ArkUI.Full
101
102| 名称   | 类型   | 必填   | 说明                                     |
103| ----- | ------ | ---- | ---------------------------------------- |
104| xs  | [Length](ts-types.md#length) | 否    | 在最小宽度类型设备上，栅格子组件的间距。    |
105| sm  | [Length](ts-types.md#length) | 否    | 在小宽度类型设备上，栅格子组件的间距。      |
106| md  | [Length](ts-types.md#length) | 否    | 在中等宽度类型设备上，栅格子组件的间距。    |
107| lg  | [Length](ts-types.md#length) | 否    | 在大宽度类型设备上，栅格子组件的间距。      |
108| xl  | [Length](ts-types.md#length) | 否    | 在特大宽度类型设备上，栅格子组件的间距。    |
109| xxl | [Length](ts-types.md#length) | 否    | 在超大宽度类型设备上，栅格子组件的间距。    |
110
111## BreakPoints
112
113设置栅格容器组件的断点。
114
115**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
116
117**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
118
119**系统能力：** SystemCapability.ArkUI.ArkUI.Full
120
121| 名称   | 类型   | 必填   | 说明                                     |
122| ----- | ------ | ---- | ---------------------------------------- |
123| value  | Array&lt;string&gt; | 否  | 设置断点位置的单调递增数组。<br>默认值：["320vp", "600vp", "840vp"]    |
124| reference  | [BreakpointsReference](#breakpointsreference枚举说明) | 否    | 断点切换参照物。<br>默认值：BreakpointsReference.WindowSize |
125```ts
126  // 启用xs、sm、md共3个断点
127  breakpoints: {value: ["100vp", "200vp"]}
128  // 启用xs、sm、md、lg共4个断点，断点范围值必须单调递增
129  breakpoints: {value: ["320vp", "600vp", "840vp"]}
130  // 启用xs、sm、md、lg、xl共5个断点，断点范围数量不可超过断点可取值数量-1
131  breakpoints: {value: ["320vp", "600vp", "840vp", "1080vp"]}
132```
133
134## BreakpointsReference枚举说明
135
136**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
137
138**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
139
140**系统能力：** SystemCapability.ArkUI.ArkUI.Full
141
142| 名称 | 说明 |
143| -------- | -------- |
144| WindowSize | 以窗口为参照。 |
145| ComponentSize | 以容器为参照。 |
146
147## GridRowDirection枚举说明
148
149**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
150
151**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
152
153**系统能力：** SystemCapability.ArkUI.ArkUI.Full
154
155| 名称 | 说明 |
156| -------- | -------- |
157| Row | 栅格元素按照行方向排列。 |
158| RowReverse | 栅格元素按照逆序行方向排列。 |
159
160**说明：**
161* 栅格元素仅支持Row/RowReverse排列，不支持column/ColumnReverse方向排列。
162* 栅格子组件仅能通过span、offset计算子组件位置与大小。多个子组件span超过规定列数时自动换行。
163* 单个元素span大小超过最大列数时后台默认span为最大column数。
164* 新一行的Offset加上子组件的span超过总列数时，将下一个子组件在新的一行放置。
165* 例：Item1: GridCol({ span: 6})， Item2: GridCol({ span: 8, offset:11})
166
167|1      | 2     | 3     | 4     | 5     | 6     | 7     | 8     | 9     | 10    | 11    | 12    |
168| ----- | ------ | ---- | ---- | -----|-----|---------|--------|------|------- |------- |------- |
169| $\circ$ | $\circ$ | $\circ$ | $\circ$ | $\circ$|$\circ$| - |  - |  - |  -  | -  | -  |
170| -     | -     | -     | -     | -     |       |       |       |       |       |   |   |
171| $\circ$ | $\circ$ | $\circ$ | $\circ$ | $\circ$|$\circ$|$\circ$|$\circ$|  |   |   |   |
172
173## 属性
174
175除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性：
176
177### alignItems<sup>10+</sup>
178
179alignItems(value: ItemAlign)
180
181设置GridRow中的GridCol垂直主轴方向对齐方式。GridCol本身也可通过alignSelf([ItemAlign](ts-appendix-enums.md#itemalign))设置自身对齐方式。当上述两种对齐方式都设置时，以GridCol自身设置为准。
182
183**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。
184
185**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
186
187**系统能力：** SystemCapability.ArkUI.ArkUI.Full
188
189**参数：**
190
191| 参数名 | 类型                                        | 必填 | 说明                                                         |
192| ------ | ------------------------------------------- | ---- | ------------------------------------------------------------ |
193| value  | [ItemAlign](ts-appendix-enums.md#itemalign) | 是   | GridRow中的GridCol垂直主轴方向对齐方式。<br/>默认值：ItemAlign.Start<br/>**说明**：<br/>ItemAlign支持的枚举：ItemAlign.Start、ItemAlign.Center、ItemAlign.End、ItemAlign.Stretch。 |
194
195
196## 事件
197
198### onBreakpointChange
199
200onBreakpointChange(callback: (breakpoints: string) => void)
201
202断点发生变化时触发回调。
203
204**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
205
206**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
207
208**系统能力：** SystemCapability.ArkUI.ArkUI.Full
209
210**参数：**
211
212| 参数名   | 类型   | 必填   | 说明   |
213| ----- | ------ | ---- | ---------------------------------------- |
214|breakpoints| string |否|取值为`"xs"`、`"sm"`、`"md"`、`"lg"`、`"xl"`、`"xxl"`。|
215
216## 示例
217
218栅格布局的基本用法。
219
220```ts
221// xxx.ets
222@Entry
223@Component
224struct GridRowExample {
225  @State bgColors: Color[] = [Color.Red, Color.Orange, Color.Yellow, Color.Green, Color.Pink, Color.Grey, Color.Blue, Color.Brown]
226  @State currentBp: string = 'unknown'
227
228  build() {
229    Column() {
230      GridRow({
231        columns: 5,
232        gutter: { x: 5, y: 10 },
233        breakpoints: { value: ["400vp", "600vp", "800vp"],
234          reference: BreakpointsReference.WindowSize },
235        direction: GridRowDirection.Row
236      }) {
237        ForEach(this.bgColors, (color: Color) => {
238          GridCol({ span: { xs: 1, sm: 2, md: 3, lg: 4 }, offset: 0, order: 0 }) {
239            Row().width("100%").height("20vp")
240          }.borderColor(color).borderWidth(2)
241        })
242      }.width("100%").height("100%")
243      .onBreakpointChange((breakpoint) => {
244        this.currentBp = breakpoint
245      })
246    }.width('80%').margin({ left: 10, top: 5, bottom: 5 }).height(200)
247    .border({ color: '#880606', width: 2 })
248  }
249}
250```
251
252![figures/gridrow.png](figures/gridrow.png)
253