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