• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# GridRow
2
3The responsive grid layout provides rules for layout design and resolves issues of dynamic layout across devices with different sizes, thereby ensuring layout consistency across layouts on different devices.
4
5The **\<GridRow>** component is used in a grid layout, together with its child component [\<GridCol>](ts-container-gridcol.md).
6
7>  **NOTE**
8>
9> This component is supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version.
10
11
12## Child Components
13
14This component can contain the **\<GridCol>** child component.
15
16
17## APIs
18GridRow(option?: {columns?: number | GridRowColumnOption, gutter?: Length | GutterOption, breakpoints?: BreakPoints, direction?: GridRowDirection})
19
20Since API version 9, this API is supported in ArkTS widgets.
21
22**Parameters**
23
24| Name|Type|Mandatory|Description|
25|-----|-----|----|----|
26|gutter|Length \| GutterOption|   No |Gutter of the grid layout.|
27|columns| number \| GridRowColumnOption |  No |Number of columns in the grid layout.|
28|breakpoints|BreakPoints|  No |Array of breakpoints for the breakpoint value and the corresponding reference based on the window or container size.|
29|direction|GridRowDirection|   No |Arrangement direction of the grid layout.|
30
31## GutterOption
32
33Provides the gutter options for the grid layout to define the spacing between child components in different directions.
34
35Since API version 9, this API is supported in ArkTS widgets.
36
37| Name  | Type  | Mandatory  | Description                                    |
38| ----- | ------ | ---- | ---------------------------------------- |
39| x  | Length \| GridRowSizeOption | No  | Horizontal spacing between grid child components.   |
40| y  | Length \| GridRowSizeOption | No  | Vertical spacing between grid child components.   |
41
42## GridRowColumnOption
43
44Describes the numbers of grid columns for different device width types.
45
46Since API version 9, this API is supported in ArkTS widgets.
47
48| Name  | Type  | Mandatory  | Description                                    |
49| ----- | ------ | ---- | ---------------------------------------- |
50| xs  | number | No   | Number of grid columns for minimum device width.   |
51| sm  | number | No   | Number of grid columns for small device width.     |
52| md  | number | No   | Number of grid columns for medium device width.   |
53| lg  | number | No   | Number of grid columns for large device width.     |
54| xl  | number | No   | Number of grid columns for extra large device width.   |
55| xxl | number | No   | Number of grid columns for extra extra large device width.   |
56
57## GridRowSizeOption
58
59Describes the gutter sizes for different device width types.
60
61Since API version 9, this API is supported in ArkTS widgets.
62
63| Name  | Type  | Mandatory  | Description                                    |
64| ----- | ------ | ---- | ---------------------------------------- |
65| xs  | Length | No   | Gutter size for minimum device width.   |
66| sm  | Length | No   | Gutter size for small device width.     |
67| md  | Length | No   | Gutter size for medium device width.   |
68| lg  | Length | No   | Gutter size for large device width.     |
69| xl  | Length | No   | Gutter size for extra large device width.   |
70| xxl | Length | No   | Gutter size for extra extra large device width.   |
71
72## BreakPoints
73
74Sets breakpoints for the responsive grid container.
75
76Since API version 9, this API is supported in ArkTS widgets.
77
78| Name  | Type  | Mandatory  | Description                                    |
79| ----- | ------ | ---- | ---------------------------------------- |
80| value  | Array&lt;string&gt; | No | Array of monotonically increasing breakpoints.<br>Default value: **["320vp", "600vp", "840vp"]**   |
81| reference  | BreakpointsReference | No   | Breakpoint switching reference.<br>Default value: **BreakpointsReference.WindowSize**|
82```ts
83  // Enable the xs, sm, and md breakpoints.
84  breakpoints: {value: ["100vp", "200vp"]}
85  // Enable four breakpoints: xs, sm, md, and lg. The breakpoint range must be monotonically increasing.
86  breakpoints: {value: ["320vp", "600vp", "840vp"]}
87  // Enable five breakpoints: xs, sm, md, lg, and xl. The number of breakpoint ranges cannot exceed the number of breakpoints minus 1.
88  breakpoints: {value: ["320vp", "600vp", "840vp", "1080vp"]}
89```
90
91## BreakpointsReference
92
93Since API version 9, this API is supported in ArkTS widgets.
94
95| Name| Description|
96| -------- | -------- |
97| WindowSize | The window is used as a reference.|
98| ComponentSize | The container is used as a reference.|
99
100## GridRowDirection
101
102Since API version 9, this API is supported in ArkTS widgets.
103
104| Name| Description|
105| -------- | -------- |
106| Row | Grid elements are arranged in the row direction.|
107| RowReverse | Grid elements are arranged in the reverse row direction.|
108
109A grid supports a maximum of six breakpoints: xs, sm, md, lg, xl and xxl, whose names cannot be changed. Assume that the input array is [n0, n1, n2, n3, n4], then the value ranges of breakpoints are as follows.
110
111|Breakpoint|Value Range|
112|---|-----------|
113|xs |[0, n0)    |
114|sm |[n0, n1)   |
115|md |[n1, n2)   |
116|lg |[n2, n3)   |
117|xl |[n3, n4)   |
118|xxl|[n4, INF)  |
119
120**NOTE**
121* Grid elements can be arranged only in the **Row** or **RowReverse** direction, but not in the **Column** or **ColumnReverse** direction.
122* The location and size of a grid child component can be calculated only based on **span** and **offset**. If the **span** values of child components add up to a number greater than the allowed number of columns, the grid will automatically wraps lines.
123* If the **span** value of a single child component exceeds the maximum number of columns, the maximum number of columns is used.
124* If a child component takes up more than the total number of columns according to its **offset** and **span** settings, it will be placed in a new row.
125* Below is the display effect of **Item1: GridCol({span: 6}), Item2: GridCol({ span: 8, offset:11})**.
126
127|1      | 2     | 3     | 4     | 5     | 6     | 7     | 8     | 9     | 10    | 11    | 12    |
128| ----- | ------ | ---- | ---- | -----|-----|---------|--------|------|------- |------- |------- |
129| $\circ$ | $\circ$ | $\circ$ | $\circ$ | $\circ$|$\circ$| - |  - |  - |  -  | -  | -  |
130| -     | -     | -     | -     | -     |       |       |       |       |       |   |   |
131| $\circ$ | $\circ$ | $\circ$ | $\circ$ | $\circ$|$\circ$|$\circ$|$\circ$|  |   |   |   |
132
133## Attributes
134
135In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
136
137| Name                      | Type                           | Description                                              |
138| ----------------------- | ----------------------------------- | ------------------------------------------- |
139| alignItems<sup>10+</sup>             | ItemAlign | Alignment mode of the **\<GridCol>** cross axis.<br>Default value: **ItemAlign.Start**<br>**NOTE**<br>**ItemAlign** supports the following enums: **ItemAlign.Start**, **ItemAlign.Center**, **ItemAlign.End**, and **ItemAlign.Stretch**.<br>The alignment mode of the **\<GridCol>** component can also be set using **alignSelf([ItemAlign](ts-appendix-enums.md#itemalign))**. If both of the preceding methods are used, the setting of **alignSelf(ItemAlign)** prevails.<br>Since API version 10, this API is supported in ArkTS widgets.|
140
141
142## Events
143
144### onBreakpointChange
145
146onBreakpointChange(callback: (breakpoints: string) => void)
147
148Triggered when the breakpoint changes.
149
150Since API version 9, this API is supported in ArkTS widgets.
151
152**Parameters**
153
154| Name  | Type  | Mandatory  | Description  |
155| ----- | ------ | ---- | ---------------------------------------- |
156|breakpoints| string |Yes|Breakpoint change.<br> The value can be **"xs"**, **"sm"**, **"md"**, **"lg"**, **"xl"**, or **"xxl"**.|
157
158## Example
159
160```ts
161// xxx.ets
162@Entry
163@Component
164struct GridRowExample {
165  @State bgColors: Color[] = [Color.Red, Color.Orange, Color.Yellow, Color.Green, Color.Pink, Color.Grey, Color.Blue, Color.Brown]
166  @State currentBp: string = 'unknown'
167
168  build() {
169    Column() {
170      GridRow({
171        columns: 5,
172        gutter: { x: 5, y: 10 },
173        breakpoints: { value: ["400vp", "600vp", "800vp"],
174          reference: BreakpointsReference.WindowSize },
175        direction: GridRowDirection.Row
176      }) {
177        ForEach(this.bgColors, (color: Color) => {
178          GridCol({ span: { xs: 1, sm: 2, md: 3, lg: 4 }, offset: 0, order: 0 }) {
179            Row().width("100%").height("20vp")
180          }.borderColor(color).borderWidth(2)
181        })
182      }.width("100%").height("100%")
183      .onBreakpointChange((breakpoint) => {
184        this.currentBp = breakpoint
185      })
186    }.width('80%').margin({ left: 10, top: 5, bottom: 5 }).height(200)
187    .border({ color: '#880606', width: 2 })
188  }
189}
190```
191
192![figures/gridrow.png](figures/gridrow.png)
193