1# GridCol 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @zju_ljz--> 5<!--Designer: @lanshouren--> 6<!--Tester: @liuli0427--> 7<!--Adviser: @HelloCrease--> 8 9栅格子组件，必须作为栅格容器组件([GridRow](ts-container-gridrow.md))的子组件使用。 10 11> **说明：** 12> 13> 该组件从API version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14 15## 子组件 16 17可以包含单个子组件。 18## 接口 19 20GridCol(option?: GridColOptions) 21 22栅格列布局组件。 23 24**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 25 26**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 27 28**系统能力：** SystemCapability.ArkUI.ArkUI.Full 29 30**参数：** 31| 参数名 | 类型 | 必填 | 说明 | 32| ------ | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 33| option | [GridColOptions](#gridcoloptions对象说明) | 否 | 栅格布局子组件参数。 | 34 35## GridColOptions对象说明 36 37设置栅格列布局组件布局选项。 38 39**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 40 41**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 42 43**系统能力：** SystemCapability.ArkUI.ArkUI.Full 44 45| 名称 | 类型 | 只读 | 可选 | 说明 | 46| -------- | -------- | -------- | -------- | -------- | 47| span | number \| [GridColColumnOption](#gridcolcolumnoption) | 否 | 是 | 栅格子组件占用栅格容器组件的列数。span为0表示该元素不参与布局计算，即不会被渲染。<br/>取值为非负整数，默认值为1 <br />非法值：按默认值处理。| 48| offset | number \| [GridColColumnOption](#gridcolcolumnoption) | 否 | 是 | 栅格子组件相对于原本位置偏移的列数。<br/>取值为非负整数，默认值为0 <br />非法值：按默认值处理。| 49| order | number \| [GridColColumnOption](#gridcolcolumnoption) | 否 | 是 | 元素的序号，根据栅格子组件的序号，从小到大对栅格子组件做排序。<br/>取值为非负整数，默认值为0。<br />非法值：按默认值处理。<br/>**说明：**<br/>当子组件不设置order或者设置相同的order，子组件按照代码顺序展示。<br/>当子组件部分设置order，部分不设置order时，未设置order的子组件依次排序靠前，设置了order的子组件按照数值从小到大排列。| 50 51`span`、`offset`、`order`属性按照`xs`、`sm`、`md`、`lg`、`xl`、`xxl`的顺序具有“继承性”，未设置值的断点将会从前一个断点取值。 52API version 20之后，`span`的继承规则见[gridcolcolumnoption](#gridcolcolumnoption)。 53 54## 属性 55除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 56 57### span 58 59span(value: number | GridColColumnOption) 60 61设置占用列数。span为0，意味着该元素不参与布局计算，即不会被渲染。 62 63**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 64 65**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 66 67**系统能力：** SystemCapability.ArkUI.ArkUI.Full 68 69**参数：** 70 71| 参数名 | 类型 | 必填 | 说明 | 72| ------ | ------------------------------------------------------------ | ---- | ------------------------ | 73| value | number \| [GridColColumnOption](#gridcolcolumnoption) | 是 | 占用列数。<br/>取值为非负整数，默认值为1。<br />非法值：按默认值处理。 | 74 75### gridColOffset 76 77gridColOffset(value: number | GridColColumnOption) 78 79设置相对于前一个栅格子组件偏移的列数。 80 81**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 82 83**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 84 85**系统能力：** SystemCapability.ArkUI.ArkUI.Full 86 87**参数：** 88 89| 参数名 | 类型 | 必填 | 说明 | 90| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------ | 91| value | number \| [GridColColumnOption](#gridcolcolumnoption) | 是 | 相对于前一个栅格子组件偏移的列数。<br/>取值为非负整数，默认值：0 <br />非法值：按默认值处理。| 92 93### order 94 95order(value: number | GridColColumnOption) 96 97设置栅格子组件的序号，根据序号从小到大对栅格子组件进行排序。 98 99**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 100 101**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 102 103**系统能力：** SystemCapability.ArkUI.ArkUI.Full 104 105**参数：** 106 107| 参数名 | 类型 | 必填 | 说明 | 108| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 109| value | number \| [GridColColumnOption](#gridcolcolumnoption) | 是 | 元素的序号，根据栅格子组件的序号，从小到大对栅格子组件做排序。<br/>取值为非负整数，默认值：0 <br />非法值：按默认值处理。| 110 111## GridColColumnOption 112 113用于自定义指定在不同宽度设备类型上，栅格子组件占据的栅格数量单位。 114 115**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 116 117**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 118 119**系统能力：** SystemCapability.ArkUI.ArkUI.Full 120 121| 名称 | 类型 | 只读 | 可选 | 说明 | 122| -------- | -------- | -------- | -------- | -------- | 123| xs | number | 否 | 是 | 在栅格大小为xs的设备上，栅格容器组件的栅格列数。 | 124| sm | number | 否 | 是 | 在栅格大小为sm的设备上，栅格容器组件的栅格列数。 | 125| md | number | 否 | 是 | 在栅格大小为md的设备上，栅格容器组件的栅格列数。 | 126| lg | number | 否 | 是 | 在栅格大小为lg的设备上，栅格容器组件的栅格列数。 | 127| xl | number | 否 | 是 | 在栅格大小为xl的设备上，栅格容器组件的栅格列数。 | 128| xxl | number | 否 | 是 | 在栅格大小为xxl的设备上，栅格容器组件的栅格列数。 | 129 130**说明：** 131- API version 20之前，仅配置部分断点下GridCol组件所占列数，取已配置的更小断点的列数补全未配置的列数。若未配置更小断点的列数，取默认值1。 132 <!--code_no_check--> 133 ```ts 134 span: {xs:2, md:4, lg:8} // 等于配置 span: {xs:2, sm:2, md:4, lg:8, xl:8, xxl:8} 135 span: {md:4, lg:8} // 等于配置 span: {xs:1, sm:1, md:4, lg:8, xl:8, xxl:8} 136 ``` 137- API version 20及以后，仅配置部分断点下GridCol组件所占列数，取已配置的更小断点的列数补全未配置的列数。若未配置更小断点的列数，取已配置的更大断点的列数补全未配置的列数。 138 <!--code_no_check--> 139 ```ts 140 span: {xs:2, md:4, lg:8} // 等于配置 span: {xs:2, sm:2, md:4, lg:8, xl:8, xxl:8} 141 span: {md:4, lg:8} // 等于配置 span: {xs:4, sm:4, md:4, lg:8, xl:8, xxl:8} 142 ``` 143- 建议手动配置不同断点下GridCol组件所占列数，避免默认补全列数的布局效果不符合预期。 144 145## 事件 146支持[通用事件](ts-component-general-events.md)。 147 148## 示例 149GridCol的基本用法示例。 150 151```ts 152// xxx.ets 153@Entry 154@Component 155struct GridColExample { 156 @State bgColors: Color[] = 157 [Color.Red, Color.Orange, Color.Yellow, Color.Green, Color.Pink, Color.Grey, Color.Blue, Color.Brown] 158 @State currentBp: string = 'unknown' 159 160 build() { 161 Column() { 162 GridRow({ 163 columns: 5, 164 gutter: { x: 5, y: 10 }, 165 breakpoints: { 166 value: ["400vp", "600vp", "800vp"], 167 reference: BreakpointsReference.WindowSize 168 }, 169 direction: GridRowDirection.Row 170 }) { 171 ForEach(this.bgColors, (color: Color) => { 172 GridCol({ 173 span: { xs: 1, sm: 2, md: 3, lg: 4 }, 174 offset: 0, 175 order: 0 176 }) { 177 Row().width("100%").height("20vp") 178 }.borderColor(color).borderWidth(2) 179 }) 180 }.width("100%").height("100%") 181 .onBreakpointChange((breakpoint) => { 182 this.currentBp = breakpoint 183 }) 184 }.width('80%').margin({ left: 10, top: 5, bottom: 5 }).height(200) 185 .border({ color: '#880606', width: 2 }) 186 } 187} 188``` 189 190
