GridRow

Note:

Currently in the beta phase.

The grid layout provides a structured regularity for layouts, addressing dynamic layout challenges across multiple sizes and devices, ensuring consistent module arrangement across different devices.

The grid container component can only be used with grid child components (GridCol) in grid layout scenarios.

Import Module

import kit.ArkUI.*

Child Components

(GridCol) is used in grid layout scenarios.

Creating Components

init(?Int32, ?Length, ?BreakPoints, ?GridRowDirection, () -> Unit)

public init(
    columns!: ?Int32,
    gutter!: ?Length = None,
    breakpoints!: ?BreakPoints = Option.None,
    direction!: ?GridRowDirection = Option.None,
    child!: () -> Unit = {=>}
)

Function: Creates a GridRow container that can include child components.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
columns	?Int32	Yes	-	Named parameter. Sets the number of layout columns. Initial value: 12.
gutter	?Length	No	None	Named parameter. Spacing between grid layouts. Initial value: 0.vp.
breakpoints	?BreakPoints	No	Option.None	Named parameter. Breakpoint sequence for breakpoint values and corresponding references based on window or container size. Initial value: BreakPoints().
direction	?GridRowDirection	No	Option.None	Named parameter. Arrangement direction of the grid layout. Initial value: GridRowDirection.Row.
child	() -> Unit	No	{=>}	Named parameter. Child components of the GridRow container.

init(?GridRowOptions, ?Length, ?BreakPoints, ?GridRowDirection, () -> Unit)

public init(
    columns!: ?GridRowOptions = None,
    gutter!: ?Length = None,
    breakpoints!: ?BreakPoints = Option.None,
    direction!: ?GridRowDirection = Option.None,
    child!: () -> Unit = {=>}
)

Function: Creates a GridRow container that can include child components.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
columns	?GridRowOptions	No	None	Named parameter. Sets the number of layout columns. Initial value: GridRowOptions()
gutter	?Length	No	None	Named parameter. Spacing between grid layouts. Initial value: 0.vp
breakpoints	?BreakPoints	No	Option.None	Named parameter. Breakpoint sequence for breakpoint values and corresponding references based on window or container size. Initial value: BreakPoints()
direction	?GridRowDirection	No	Option.None	Named parameter. Arrangement direction of the grid layout. Initial value: GridRowDirection.Row
child	() -> Unit	No	{=>}	Named parameter. Child components of the GridRow container.

init(?Int32, ?GutterOption, ?BreakPoints, ?GridRowDirection, () -> Unit)

public init(
    columns!: ?Int32,
    gutter!: ?GutterOption,
    breakpoints!: ?BreakPoints = Option.None,
    direction!: ?GridRowDirection = Option.None,
    child!: () -> Unit = {=>}
)

Function: Creates a GridRow container that can include child components.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
columns	?Int32	Yes	-	Named parameter. Sets the number of layout columns. Initial value: 12
gutter	?GutterOption	Yes	-	Named parameter. Spacing between grid layouts.
breakpoints	?BreakPoints	No	Option.None	Named parameter. Breakpoint sequence for breakpoint values and corresponding references based on window or container size. Initial value: BreakPoints()
direction	?GridRowDirection	No	Option.None	Named parameter. Arrangement direction of the grid layout. Initial value: GridRowDirection.Row
child	() -> Unit	No	{=>}	Named parameter. Child components of the GridRow container.

init(?GridRowOptions, ?GutterOption, ?BreakPoints, ?GridRowDirection, () -> Unit)

public init(
    columns!: ?GridRowOptions = None,
    gutter!: ?GutterOption,
    breakpoints!: ?BreakPoints = Option.None,
    direction!: ?GridRowDirection = Option.None,
    child!: () -> Unit = {=>})

Function: Creates a GridRow container that can include child components.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
columns	?GridRowOptions	No	None	Named parameter. Sets the number of layout columns. Initial value: GridRowOptions().
gutter	?GutterOption	Yes	-	Named parameter. Spacing between grid layouts.
breakpoints	?BreakPoints	No	Option.None	Named parameter. Breakpoint sequence for breakpoint values and corresponding references based on window or container size. Initial value: BreakPoints().
direction	?GridRowDirection	No	Option.None	Named parameter. Arrangement direction of the grid layout. Initial value: GridRowDirection.Row.
child	() -> Unit	No	{=>}	Named parameter. Child components of the GridRow container.

Common Attributes/Events

Common Attributes: All supported.

Common Events: All supported.

Component Attributes

func alignItems(?ItemAlign)

public func alignItems(value: ?ItemAlign): This

Function: Sets the vertical main axis alignment of GridCol within GridRow. GridCol itself can also set its own alignment via alignSelf(ItemAlign). If both alignment methods are set, the GridCol's own setting takes precedence.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
value	?ItemAlign	Yes	-	Vertical main axis alignment of GridCol within GridRow. Initial value: ItemAlign.Start.

Component Events

func onBreakpointChange(?(String) -> Unit)

public func onBreakpointChange(callback: ?(String) -> Unit): This

Function: Triggers a callback when the breakpoint changes.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
callback	?(String)->Unit	Yes	-	Callback triggered when the breakpoint changes. Values: "xs", "sm", "md", "lg", "xl", "xxl". Initial value: { res: String => }.

Basic Type Definitions

class BreakPoints

public class BreakPoints {
    public var value: ?Array<Length>
    public var reference: ?BreakpointsReference
    public init(value!: ?Array<Length> = None,
        reference!: ?BreakpointsReference = None
    )
}

Function: Constructs breakpoints for the grid container component.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

var reference

public var reference: ?BreakpointsReference

Function: Reference for breakpoint switching.

Type: ?BreakpointsReference

Read/Write: Readable and Writable

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

var value

public var value: ?Array<Length>

Function: Sets a monotonically increasing array of breakpoint positions.

Type: ?Array<Length>

Read/Write: Readable and Writable

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

init(?Array<Length>, ?BreakpointsReference)

public init(value!: ?Array<Length> = None,
    reference!: ?BreakpointsReference = None
)

Function: Constructs a BreakPoints object.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
value	?Array<Length>	No	None	Named parameter. Sets a monotonically increasing array of breakpoint positions. Initial value: [320.vp, 600.vp, 840.vp]
reference	?BreakpointsReference	No	None	Named parameter. Reference for breakpoint switching. Initial value: BreakpointsReference.WindowSize

class GridRowSizeOption

public class GridRowSizeOption {
    public var xs: ?Length
    public var sm: ?Length
    public var md: ?Length
    public var lg: ?Length
    public var xl: ?Length
    public var xxl: ?Length
    public init(
        xs!: ?Length = None,
        sm!: ?Length = None,
        md!: ?Length = None,
        lg!: ?Length = None,
        xl!: ?Length = None,
        xxl!: ?Length = None
    )
    public init(value: ?Length)
}

Function: Gutter size for grids on devices of different widths.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

var lg

public var lg: ?Length

Function: Large-width type devices.

Type: ?Length

Read/Write: Readable and Writable

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

var md

public var md: ?Length

Function: Medium-width type devices.

Type: ?Length

Read/Write: Readable and Writable

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

var sm

public var sm: ?Length

Function: Small-width type devices.

Type: ?Length

Read/Write: Readable and Writable

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

var xl

public var xl: ?Length

Function: Extra-large-width type devices.

Type: ?Length

Read/Write: Readable and Writable

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

var xs

public var xs: ?Length

Function: Minimum-width type devices.

Type: ?Length

Read/Write: Readable and Writable

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

var xxl

public var xxl: ?Length

Function: Super-large-width type devices.

Type: ?Length

Read/Write: Readable and Writable

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

init(?Length, ?Length, ?Length, ?Length, ?Length, ?Length)

public init(
    xs!: ?Length = None,
    sm!: ?Length = None,
    md!: ?Length = None,
    lg!: ?Length = None,
    xl!: ?Length = None,
    xxl!: ?Length = None
)

Function: Constructs a GridRowSizeOption object.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
xs	?Length	No	None	Named parameter. Number of columns occupied or offset by grid child components on xs-sized devices. Initial value: 0.vp
sm	?Length	No	None	Named parameter. Number of columns occupied or offset by grid child components on sm-sized devices. Initial value: 0.vp
md	?Length	No	None	Named parameter. Number of columns occupied or offset by grid child components on md-sized devices. Initial value: 0.vp
lg	?Length	No	None	Named parameter. Number of columns occupied or offset by grid child components on lg-sized devices. Initial value: 0.vp
xl	?Length	No	None	Named parameter. Number of columns occupied or offset by grid child components on xl-sized devices. Initial value: 0.vp
xxl	?Length	No	None	Named parameter. Number of columns occupied or offset by grid child components on xxl-sized devices. Initial value: 0.vp

init(?Length)

public init(value: ?Length)

Function: Constructs a GridRowSizeOption object.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
value	?Length	Yes	-	Number of columns occupied or offset by grid child components on devices of any grid size. Initial value: 0.vp

class GutterOption

public class GutterOption {
    public init(x!: ?Length = None, y!: ?Length = None)
    public init(x!: ?GridRowSizeOption, y!: ?GridRowSizeOption)
}

Function: Grid layout spacing type, used to describe the spacing between grid subcomponents in different directions.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

init(?Length, ?Length)

public init(x!: ?Length = None, y!: ?Length = None)

Function: Constructs a GutterOption object.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
x	?Length	No	None	Named parameter. Spacing of grid subcomponents in the x-direction. Initial value: 0.vp
y	?Length	No	None	Named parameter. Spacing of grid subcomponents in the y-direction. Initial value: 0.vp

init(?GridRowSizeOption, ?GridRowSizeOption)

public init(x!: ?GridRowSizeOption, y!: ?GridRowSizeOption)

Function: Constructs a GutterOption object.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
x	?GridRowSizeOption	No	None	Named parameter. Spacing of grid subcomponents in the x-direction. Initial value: GridRowSizeOption()
y	?GridRowSizeOption	No	None	Named parameter. Spacing of grid subcomponents in the y-direction. Initial value: GridRowSizeOption()

class GridRowOptions

public class GridRowOptions {
    public var xs: ?Int32
    public var sm: ?Int32
    public var md: ?Int32
    public var lg: ?Int32
    public var xl: ?Int32
    public var xxl: ?Int32
    public init(
        xs!: ?Int32 = None,
        sm!: ?Int32 = None,
        md!: ?Int32 = None,
        lg!: ?Int32 = None,
        xl!: ?Int32 = None,
        xxl!: ?Int32 = None
    )
    public init(value: ?Int32)
}

Function: Number of grid columns under different device width types.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

var lg

public var lg: ?Int32

Function: Named parameter. Number of columns occupied or offset by grid subcomponents on devices with lg grid size.

Type: ?Int32

Read/Write: Readable and Writable

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

var md

public var md: ?Int32

Function: Named parameter. Number of columns occupied or offset by grid subcomponents on devices with md grid size.

Type: ?Int32

Read/Write: Readable and Writable

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

var sm

public var sm: ?Int32

Function: Named parameter. Number of columns occupied or offset by grid subcomponents on devices with sm grid size.

Type: ?Int32

Read/Write: Readable and Writable

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

var xl

public var xl: ?Int32

Function: Named parameter. Number of columns occupied or offset by grid subcomponents on devices with xl grid size.

Type: ?Int32

Read/Write: Readable and Writable

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

var xs

public var xs: ?Int32

Function: Named parameter. Number of columns occupied or offset by grid subcomponents on devices with xs grid size.

Type: ?Int32

Read/Write: Readable and Writable

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

var xxl

public var xxl: ?Int32

Function: Named parameter. Number of columns occupied or offset by grid subcomponents on devices with xxl grid size.

Type: ?Int32

Read/Write: Readable and Writable

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

init(?Int32, ?Int32, ?Int32, ?Int32, ?Int32, ?Int32)

public init(
    xs!: ?Int32 = None,
    sm!: ?Int32 = None,
    md!: ?Int32 = None,
    lg!: ?Int32 = None,
    xl!: ?Int32 = None,
    xxl!: ?Int32 = None
)

Function: Constructs a GridRowOptions object.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
xs	?Int32	No	None	Named parameter. Number of columns occupied or offset by grid subcomponents on devices with xs grid size. Initial value: 2
sm	?Int32	No	None	Named parameter. Number of columns occupied or offset by grid subcomponents on devices with sm grid size. Initial value: 4
md	?Int32	No	None	Named parameter. Number of columns occupied or offset by grid subcomponents on devices with md grid size. Initial value: 8
lg	?Int32	No	None	Named parameter. Number of columns occupied or offset by grid subcomponents on devices with lg grid size. Initial value: 12
xl	?Int32	No	None	Named parameter. Number of columns occupied or offset by grid subcomponents on devices with xl grid size. Initial value: 12
xxl	?Int32	No	None	Named parameter. Number of columns occupied or offset by grid subcomponents on devices with xxl grid size. Initial value: 12

init(?Int32)

public init(value: ?Int32)

Function: Constructs a GridRowOptions object.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
value	?Int32	Yes	-	Number of columns occupied or offset by grid subcomponents on devices of any grid size. Initial value: 12

enum BreakpointsReference

public enum BreakpointsReference <: Equatable<BreakpointsReference> {
    | WindowSize
    | ComponentSize
    | ...
}

Function: Sets the reference to either window size or container size.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parent Type: Equatable<BreakpointsReference>

ComponentSize

ComponentSize

Function: Uses container size as reference.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

WindowSize

WindowSize

Function: Uses window size as reference.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

operator func !=(BreakpointsReference)

public operator func !=(other: BreakpointsReference): Bool

Function: Compares whether two enum values are not equal.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
other	BreakpointsReference	Yes	-	Another enum value to compare.

Return Value:

Type	Description
Bool	Returns true if the two enum values are not equal, otherwise returns false.

operator func ==(BreakpointsReference)

public operator func ==(other: BreakpointsReference): Bool

Function: Compares whether two enum values are equal.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
other	BreakpointsReference	Yes	-	Another enum value to compare.

Return Value:

Type	Description
Bool	Returns true if the two enum values are equal, otherwise returns false.

enum GridRowDirection

public enum GridRowDirection <: Equatable<GridRowDirection> {
    | Row
    | RowReverse
    | ...
}

Function: Arranges grid elements in row or column direction.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parent Type: Equatable<GridRowDirection>

Row

Row

Function: Uses row direction as the main axis for layout mode.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

RowReverse

RowReverse

Function: Layouts in the opposite direction of Row.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

operator func !=(GridRowDirection)

public operator func !=(other: GridRowDirection): Bool

Function: Compares whether two enum values are not equal.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22.

Parameters:

Parameter	Type	Required	Default	Description
other	GridRowDirection	Yes	-	Another enum value to compare.

Return Value:

Type	Description
Bool	Returns true if the two enum values are not equal, otherwise returns false.

operator func ==(GridRowDirection)

public operator func ==(other: GridRowDirection): Bool

Function: Compares whether two enum values are equal.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter	Type	Required	Default	Description
other	GridRowDirection	Yes	-	Another enum value to compare.

Return Value:

Type	Description
Bool	Returns true if the two enum values are equal, otherwise returns false.

package ohos_app_cangjie_entry
import kit.ArkUI.*
import ohos.arkui.state_macro_manage.*

@Entry
@Component
class EntryView {
    var bgColors: Array<Color> = [Color.Red, Color.Green, Color.Blue, Color.Gray, Color.Red, Color.Green, Color.Blue, Color.Gray]
    var currentBp: String = ""
    func build() {
        Column {
            GridRow(
                // Set the number of grid columns for different device width types.
                // xs: minimum width devices   sm: small width devices    md: medium width devices.
                // lg: large width devices     xl: extra large width devices  xxl: super large width devices.
                columns: GridRowOptions(xs: 6, sm: 7, md: 8, lg: 9, xl: 10, xxl: 11),
                // Set grid layout spacing, where x represents horizontal and y represents vertical direction.
                gutter: GutterOption(x: 5.vp, y: 10.vp),
                // Set breakpoint values and corresponding references based on window or container size.
                breakpoints: BreakPoints(
                    // Enable four breakpoints: xs, sm, md, lg
                    value: [200.vp, 300.vp, 400.vp], // Set a monotonically increasing array for breakpoint positions.
                    reference: BreakpointsReference.WindowSize
                ), // Set to use window as reference.
                // Set grid layout direction, arranged in row direction.
                direction: GridRowDirection.Row
            ) {
                // Loop render grids with colors from bgColors
                ForEach(
                    bgColors,
                    itemGeneratorFunc: {
                        color: Color, index: Int64 => GridCol() {
                            Row()
                                .width(100.percent)
                                .height(20.vp)
                        }
                        .borderWidth(2.vp)
                        .borderColor(color)
                        .span(1)
                    }
                )
            }
                .width(100.percent)
                .height(200)
                .onBreakpointChange({bp => currentBp = bp})
                .alignItems(ItemAlign.Center) // Set vertical main axis alignment for GridCol in GridRow. Here set to center alignment.

            GridRow(
                // Set layout column count to 5
                columns: 5,
                // Set grid layout spacing: 5vp horizontal, 10vp vertical.
                gutter: GutterOption(x: 5.vp, y: 10.vp),
                // Set breakpoint values and corresponding references based on window or container size.
                breakpoints: BreakPoints(
                    // Enable four breakpoints: xs, sm, md, lg
                    value: [400.vp, 600.vp, 800.vp], // Set a monotonically increasing array for breakpoint positions.
                    reference: BreakpointsReference.WindowSize // Set to use window as reference.
                ),
                direction: GridRowDirection.Row
            ) {
                ForEach(
                    bgColors,
                    itemGeneratorFunc: {
                        color: Color, index: Int64 => GridCol() {
                            Row()
                                .width(100.percent)
                                .height(20.vp)
                        }
                        .borderWidth(2.vp)
                        .borderColor(color)
                        .span(GridColOptions(xs: 2, sm: 3, md: 4, lg: 5, xl: 6, xxl: 7))
                    }
                )
            }
            .width(100.percent)
            .height(100.percent)
            .onBreakpointChange({bp => currentBp = bp})
            .alignItems(ItemAlign.Center)
        }
        .margin(left: 10, right: 10, top: 5, bottom: 5)
        .height(400)
    }
}

grid_row