Name	Type	Mandatory	Description
option	GridColOptions	No	Options of the GridCol component.

Name	Type	Read-Only	Optional	Description
span	number \| GridColColumnOption	No	Yes	Number of columns occupied by the component. If it is set to 0, the component is not involved in layout calculation, that is, the component is not rendered. The value must be a non-negative integer. Default value: 1. Invalid values are treated as the default value.
offset	number \| GridColColumnOption	No	Yes	Number of offset columns relative to the original position of the component. The value must be a non-negative integer. Default value: 0. Invalid values are treated as the default value.
order	number \| GridColColumnOption	No	Yes	Sequence number of the component. Child components of the grid are sorted in ascending order based on their sequence numbers. The value must be a non-negative integer. Default value: 0. Invalid values are treated as the default value. NOTE If a child component shares an order value with another child component or does not have order set, it is displayed based on its code sequence number. If order is not set for all child components, those that have order set are displayed after those that do not and are sorted in ascending order based on the value.

Name	Type	Mandatory	Description
value	number \| GridColColumnOption	Yes	Number of occupied columns. The value must be a non-negative integer. Default value: 1. Invalid values are treated as the default value.

Name	Type	Mandatory	Description
value	number \| GridColColumnOption	Yes	Number of offset columns relative to the previous child component of the grid The value must be a non-negative integer. Default value: 0. Invalid values are treated as the default value.

Name	Type	Mandatory	Description
value	number \| GridColColumnOption	Yes	Sequence number of the component. Child components of the grid are sorted in ascending order based on their sequence numbers. The value must be a non-negative integer. Default value: 0. Invalid values are treated as the default value.

In versions earlier than API version 20: When you configure GridCol column spans only at specific breakpoints, unconfigured breakpoints inherit values from the next smaller configured breakpoint. If no smaller breakpoint is configured, the default value of 1 is used.
```
span: {xs:2, md:4, lg:8} // Equivalent to span: {xs:2, sm:2, md:4, lg:8, xl:8, xxl:8}.
span: {md:4, lg:8} // Equivalent to span: {xs:1, sm:1, md:4, lg:8, xl:8, xxl:8}.
```
Since API version 20: When you configure GridCol column spans only at specific breakpoints, unconfigured breakpoints inherit values from the next smaller configured breakpoint. If no smaller breakpoint exists, values are inherited from the next larger configured breakpoint.
```
span: {xs:2, md:4, lg:8} // Equivalent to span: {xs:2, sm:2, md:4, lg:8, xl:8, xxl:8}.
span: {md:4, lg:8} // Equivalent to span: {xs:4, sm:4, md:4, lg:8, xl:8, xxl:8}.
```
Recommendation: Explicitly configure GridCol column spans for all required breakpoints to prevent unexpected layout behavior caused by automatic value inheritance.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Read-Only	Optional	Description
xs	number	No	Yes	Number of grid columns on the device where the grid size is xs.
sm	number	No	Yes	Number of grid columns on the device where the grid size is sm.
md	number	No	Yes	Number of grid columns on the device where the grid size is md.
lg	number	No	Yes	Number of grid columns on the device where the grid size is lg.
xl	number	No	Yes	Number of grid columns on the device where the grid size is xl.
xxl	number	No	Yes	Number of grid columns on the device where the grid size is xxl.

Events

The universal events are supported.

Example

This example demonstrates the basic usage of GridCol.

// xxx.ets
@Entry
@Component
struct GridColExample {
  @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

Child Components

APIs

GridColOptions

Attributes

[h2]span

[h2]gridColOffset

[h2]order

GridColColumnOption

Events

Example