栅格设置可以为布局提供规律性的结构,解决多尺寸多设备的动态布局问题,保证不同设备上各个模块的布局一致性,适用于响应式布局开发、多设备UI适配、跨设备布局统一等场景。
从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
从API version 9开始,该模块不再维护,推荐使用新组件GridCol、GridRow替代。其中useSizeType从API version 9开始废弃,gridSpan和gridOffset从API version 14开始废弃。
栅格布局的列宽、列间距由距离最近的GridContainer父组件决定。GridContainer用于定义栅格系统的总列数、列间距、尺寸断点等参数。使用栅格属性的组件树上至少需要有1个GridContainer容器组件。
useSizeType、gridSpan、gridOffset属性调用时其父组件或祖先组件必须是GridContainer。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 参数类型 | 描述 |
|---|---|---|
| useSizeType(deprecated) | { xs?: number | { span: number, offset: number }, sm?: number | { span: number, offset: number }, md?: number | { span: number, offset: number }, lg?: number | { span: number, offset: number } } | 设置在特定设备宽度类型下的占用列数和偏移列数,span:占用列数(需为非负整数)。传入负数或超出GridContainer总列数时,使用默认值;offset:偏移列数(需为非负整数)。传入负数时,使用默认值0。 当值为number类型时,仅设置列数,当格式如{"span": 1, "offset": 0}时,指同时设置占用列数与偏移列数。 - xs:指设备宽度类型为SizeType.XS(<320vp)时的占用列数和偏移列数。 - sm:指设备宽度类型为SizeType.SM(320vp-600vp)时的占用列数和偏移列数。 - md:指设备宽度类型为SizeType.MD(600vp-840vp)时的占用列数和偏移列数。 - lg:指设备宽度类型为SizeType.LG(≥840vp)时的占用列数和偏移列数。 各尺寸类型的详细断点配置请参见GridContainer。 说明: - 调用该属性时,其父组件或祖先组件必须是GridContainer。 从API version 7开始支持,从API version 9开始废弃,建议使用新组件GridCol、GridRow替代。 |
| gridSpan(deprecated) | number | 默认占用列数,指useSizeType属性没有设置对应尺寸的列数(span)时,占用的栅格列数,需为非负整数。传入负数或超出GridContainer总列数时,使用默认值1。 说明: - 调用该属性时,其父组件或祖先组件必须是GridContainer。 - 设置了栅格span属性,组件的宽度由栅格布局决定。 默认值:1 元服务API: 从API version 11开始,该接口支持在元服务中使用。 从API version 7开始支持,从API version 14开始废弃,建议使用新组件GridCol、GridRow替代。 |
| gridOffset(deprecated) | number | 默认偏移列数,指useSizeType属性没有设置对应尺寸的偏移(offset)时,当前组件沿着父组件Start方向偏移的列数,即组件起始位置相对于父组件Start方向偏移n列,需为非负整数。传入负数时,使用默认值0。当useSizeType设置了对应尺寸的offset时,gridOffset设置无效。 说明: - 调用该属性时,其父组件或祖先组件必须是GridContainer。 - 配置该属性后,当前组件在父组件水平方向的布局不再跟随父组件原有的布局方式,而是沿着父组件的Start方向偏移一定位移。 - 偏移位移 = (列宽 + 间距)* 偏移列数。 - 设置了偏移(gridOffset)的组件之后的兄弟组件会根据该组件进行相对布局。 默认值:0 元服务API: 从API version 11开始,该接口支持在元服务中使用。 从API version 7开始支持,从API version 14开始废弃,建议使用新组件GridCol、GridRow替代。 |
设置不同设备类型下的栅格配置。gridSpan和gridOffset用于设置默认占用列数和偏移列数,仅在useSizeType未配置对应尺寸时生效。示例中useSizeType配置了sm尺寸的值(span: 2, offset: 1),若要在其他未配置的尺寸下实现相同的栅格效果,可通过gridSpan和gridOffset设置默认值。
// xxx.ets
@Entry
@Component
struct GridContainerExample1 {
build() {
Column() {
Text('useSizeType').fontSize(15).fontColor(0xCCCCCC).width('90%')
GridContainer() {
Row() {
Row() {
Text('Left').fontSize(25)
}
.useSizeType({
xs: { span: 1, offset: 0 }, sm: { span: 1, offset: 0 },
md: { span: 1, offset: 0 }, lg: { span: 2, offset: 0 }
})
.height("100%")
.backgroundColor(0x66bbb2cb)
Row() {
Text('Center').fontSize(25)
}
.useSizeType({
xs: { span: 1, offset: 0 }, sm: { span: 2, offset: 1 },
md: { span: 5, offset: 1 }, lg: { span: 7, offset: 2 }
})
.height("100%")
.backgroundColor(0x66b6c5d1)
Row() {
Text('Right').fontSize(25)
}
.useSizeType({
xs: { span: 1, offset: 0 }, sm: { span: 1, offset: 3 },
md: { span: 2, offset: 6 }, lg: { span: 3, offset: 9 }
})
.height("100%")
.backgroundColor(0x66bbb2cb)
}
.height(200)
}
.backgroundColor(0xf1f3f5)
.margin({ top: 10 })
// 单独设置组件的span和offset,在sm尺寸大小的设备上使用useSizeType中sm的数据实现一样的效果
Text('gridSpan,gridOffset').fontSize(15).fontColor(0xCCCCCC).width('90%')
GridContainer() {
Row() {
Row() {
Text('Left').fontSize(25)
}
.gridSpan(1)
.height("100%")
.backgroundColor(0x66bbb2cb)
Row() {
Text('Center').fontSize(25)
}
.gridSpan(2)
.gridOffset(1)
.height("100%")
.backgroundColor(0x66b6c5d1)
Row() {
Text('Right').fontSize(25)
}
.gridSpan(1)
.gridOffset(3)
.height("100%")
.backgroundColor(0x66bbb2cb)
}.height(200)
}
}
}
} 图1 设备宽度为SM

图2 设备宽度为MD

图3 设备宽度为LG

图4 单独设置gridSpan和gridOffset在特定屏幕大小下的效果与useSizeType效果一致
