HarmonyOS API:容器组件
版本:v3.1 Beta
GridRow
更新时间: 2023-02-17 09:19
栅格容器组件,仅可以和栅格子组件(GridCol)在栅格布局场景中使用。
说明
该组件从API Version 9开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
子组件
可以包含GridCol子组件。
接口
GridRow(option?: {columns?: number | GridRowColumnOption, gutter?: Length | GutterOption, breakpoints?: BreakPoints, direction?: GridRowDirection})
参数:
参数名 | 类型 | 必填 | 说明 |
gutter | Length | GutterOption | 否 | 栅格布局间距,x代表水平方向。 |
columns | number | GridRowColumnOption | 否 | 设置布局列数。 |
breakpoints | BreakPoints | 否 | 设置断点值的断点数列以及基于窗口或容器尺寸的相应参照。 |
direction | GridRowDirection | 否 | 栅格布局排列方向。 |
GutterOption
参数名 | 参数类型 | 必填 | 参数描述 |
x | Length | GridRowSizeOption | 否 | 水平gutter option。 |
y | Length | GridRowSizeOption | 否 | 竖直gutter option。 |
GridRowColumnOption
栅格在不同宽度设备类型下,栅格列数。
参数名 | 参数类型 | 必填 | 参数描述 |
xs | number | 否 | 最小宽度类型设备。 |
sm | number | 否 | 小宽度类型设备。 |
md | number | 否 | 中等宽度类型设备。 |
lg | number | 否 | 大宽度类型设备。 |
xl | number | 否 | 特大宽度类型设备。 |
xxl | number | 否 | 超大宽度类型设备。 |
GridRowSizeOption
栅格在不同宽度设备类型下,gutter的大小。
参数名 | 参数类型 | 必填 | 参数描述 |
xs | Length | 否 | 最小宽度类型设备。 |
sm | Length | 否 | 小宽度类型设备。 |
md | Length | 否 | 中等宽度类型设备。 |
lg | Length | 否 | 大宽度类型设备。 |
xl | Length | 否 | 特大宽度类型设备。 |
xxl | Length | 否 | 超大宽度类型设备。 |
BreakPoints
参数名 | 参数类型 | 必填 | 参数描述 |
value | Array<string> | 否 | 设置断点位置的单调递增数组。 默认值:["320vp", "520vp", "840vp"] |
reference | BreakpointsReference | 否 | 断点切换参照物。 |
// 启用xs、sm、md共3个断点
breakpoints: {value: ["100vp", "200vp"]}
// 启用xs、sm、md、lg共4个断点,断点范围值必须单调递增
breakpoints: {value: ["320vp", "520vp", "840vp"]}
// 启用xs、sm、md、lg、xl共5个断点,断点范围数量不可超过断点可取值数量-1
breakpoints: {value: ["320vp", "520vp", "840vp", "1080vp"]}
BreakpointsReference枚举类型
枚举名 | 描述 |
WindowSize | 以窗口为参照。 |
ComponentSize | 以容器为参照。 |
GridRowDirection枚举类型
枚举名 | 描述 |
Row | 栅格元素按照行方向排列。 |
RowReverse | 栅格元素按照逆序行方向排列。 |
栅格最多支持xs、sm、md、lg、xl、xxl六个断点,且名称不可修改。假设传入的数组是[n0, n1, n2, n3, n4],各个断点取值如下:
断点 | 取值范围 |
xs | [0, n0) |
sm | [n0, n1) |
md | [n1, n2) |
lg | [n2, n3) |
xl | [n3, n4) |
xxl | [n4, INF) |
说明:
- 栅格元素仅支持Row/RowReverse排列,不支持column/ColumnReverse方向排列。
- 栅格子组件仅能通过span、offset计算子组件位置与大小。多个子组件span超过规定列数时自动换行。
- 单个元素span大小超过最大列数时后台默认span为最大column数。
- 新一行的Offset加上子组件的span超过总列数时,将下一个子组件在新的一行放置。
- 例:Item1: GridCol({ span: 6}), Item2: GridCol({ span: 8, offset:11})
1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
$\circ$ | $\circ$ | $\circ$ | $\circ$ | $\circ$ | $\circ$ | - | - | - | - | - | - |
- | - | - | - | - | |||||||
$\circ$ | $\circ$ | $\circ$ | $\circ$ | $\circ$ | $\circ$ | $\circ$ | $\circ$ |
属性
支持通用属性。
事件
onBreakpointChange
onBreakpointChange(callback: (breakpoints: string) => void)
参数:
参数名 | 参数类型 | 必填 | 说明 |
breakpoints | string | 是 | 断点发生变化时触发回调 取值为"xs"、"sm"、"md"、"lg"、"xl"、"xxl"。 |
示例
// xxx.ets
@Entry
@Component
struct GridRowExample {
@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) => {
GridCol({ span: { xs: 1, sm: 2, md: 3, lg: 4 } }) {
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 })
}
}
Grid
更新时间: 2023-02-17 09:19
网格容器,由“行”和“列”分割的单元格所组成,通过指定“项目”所在的单元格做出各种各样的布局。
说明
该组件从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
子组件
包含GridItem子组件。
接口
Grid(scroller?: Scroller)
参数:
参数名 | 参数类型 | 必填 | 参数描述 |
scroller | 否 | 可滚动组件的控制器。用于与可滚动组件进行绑定。 |
属性
除支持通用属性外,还支持以下属性:
名称 | 参数类型 | 描述 |
columnsTemplate | string | 设置当前网格布局列的数量,不设置时默认1列。 例如, '1fr 1fr 2fr' 是将父组件分3列,将父组件允许的宽分为4等份,第一列占1份,第二列占1份,第三列占2份。 |
rowsTemplate | string | 设置当前网格布局行的数量,不设置时默认1行。 例如, '1fr 1fr 2fr'是将父组件分三行,将父组件允许的高分为4等份,第一行占1份,第二行占一份,第三行占2份。 |
columnsGap | Length | 设置列与列的间距。 默认值:0 |
rowsGap | Length | 设置行与行的间距。 默认值:0 |
scrollBar | 设置滚动条状态。 默认值:BarState.Off | |
scrollBarColor | string | number | Color | 设置滚动条的颜色。 |
scrollBarWidth | string | number | 设置滚动条的宽度。 |
cachedCount | number | 设置预加载的GridItem的数量。具体使用可参考减少应用白块说明。 默认值:1 |
editMode 8+ | boolean | 设置Grid是否进入编辑模式,进入编辑模式可以拖拽Grid组件内部GridItem。 默认值:flase |
layoutDirection8+ | GridDirection | 设置布局的主轴方向。 默认值:GridDirection.Row |
maxCount8+ | number | 当layoutDirection是Row/RowReverse时,表示可显示的最大列数 当layoutDirection是Column/ColumnReverse时,表示可显示的最大行数。 默认值:Infinity |
minCount8+ | number | 当layoutDirection是Row/RowReverse时,表示可显示的最小列数。 当layoutDirection是Column/ColumnReverse时,表示可显示的最小行数。 默认值:1 |
cellLength8+ | number | 当layoutDirection是Row/RowReverse时,表示一行的高度。 当layoutDirection是Column/ColumnReverse时,表示一列的宽度。 默认值:第一个元素的大小 |
multiSelectable8+ | boolean | 是否开启鼠标框选。 默认值:false - false:关闭框选。 - true:开启框选。 |
supportAnimation8+ | boolean | 是否支持动画。 默认值:false |
Grid组件根据rowsTemplate、columnsTemplate属性的设置情况,可分为以下三种布局模式:
1、rowsTemplate、columnsTemplate同时设置:
Grid只展示固定行列数的元素,其余元素不展示,且Grid不可滚动。例如rowsTemplate、columnsTemplate都设置为"1fr 1fr"时,则仅展示两行两列,共4个元素,其他元素不展示。
此模式下以下属性不生效:layoutDirection、maxCount、minCount、cellLength。
2、rowsTemplate、columnsTemplate仅设置其中的一个:
元素按照设置的方向进行排布,超出的元素可通过滚动的方式展示。例如Grid有十个元素,且设置columnsTemplate为"1fr 1fr 1fr",则Grid有三列,元素先填满一行,再填充下一行。在Grid区域外的元素,可通过竖直方向的滚动,进行展示。
此模式下以下属性不生效:layoutDirection、maxCount、minCount、cellLength。
3、rowsTemplate、columnsTemplate都不设置:
元素在layoutDirection方向上排布,列数由Grid的宽度、首个元素的宽度、minCount、maxCount、columnsGap共同决定;行数由Grid高度、首个元素高度、cellLength、rowsGap共同决定。超出行列容纳范围的元素不显示,也不能通过滚动进行展示。
此模式下仅生效以下属性:layoutDirection、maxCount、minCount、cellLength、editMode、columnsGap、rowsGap。
GridDirection8+枚举说明
名称 | 描述 |
Row | 主轴布局方向沿水平方向布局,即自左往右先填满一行,再去填下一行。 |
Column | 主轴布局方向沿垂直方向布局,即自上往下先填满一列,再去填下一列。 |
RowReverse | 主轴布局方向沿水平方向反向布局,即自右往左先填满一行,再去填下一行。 |
ColumnReverse | 主轴布局方向沿垂直方向反向布局,即自下往上先填满一列,再去填下一列。 |
事件
除支持通用事件外,还支持以下事件:
名称 | 功能描述 |
onScrollIndex(event: (first: number) => void) | 当前网格显示的起始位置item发生变化时触发。 - first: 当前显示的网格起始位置的索引值。 |
onItemDragStart(event: (event: ItemDragInfo, itemIndex: number) => (() => any) | void) | 开始拖拽网格元素时触发。 该接口能力在HarmonyOS 3.1 Beta1暂不支持。 - event: 见ItemDragInfo对象说明。 - itemIndex: 被拖拽网格元素索引值。 |
onItemDragEnter(event: (event: ItemDragInfo) => void) | 拖拽进入网格元素范围内时触发。 该接口能力在HarmonyOS 3.1 Beta1暂不支持。 - event: 见ItemDragInfo对象说明。 |
onItemDragMove(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number) => void) | 拖拽在网格元素范围内移动时触发。 该接口能力在HarmonyOS 3.1 Beta1暂不支持。 - event: 见ItemDragInfo对象说明。 - itemIndex: 拖拽起始位置。 - insertIndex: 拖拽插入位置。 |
onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void) | 拖拽离开网格元素时触发。 该接口能力在HarmonyOS 3.1 Beta1暂不支持。 - event: 见ItemDragInfo对象说明。 - itemIndex: 拖拽离开的网格元素索引值。 |
onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void) | 绑定该事件的网格元素可作为拖拽释放目标,当在网格元素内停止拖拽时触发。 该接口能力在HarmonyOS 3.1 Beta1暂不支持。 - event: 见ItemDragInfo对象说明。 - itemIndex: 拖拽起始位置。 - insertIndex: 拖拽插入位置。 - isSuccess: 是否成功释放。 |
ItemDragInfo对象说明
名称 | 类型 | 描述 |
x | number | 当前拖拽点的x坐标。 |
y | number | 当前拖拽点的y坐标。 |
示例
// xxx.ets
@Entry
@Component
struct GridExample {
@State Number: String[] = ['0', '1', '2', '3', '4']
scroller: Scroller = new Scroller()
build() {
Column({ space: 5 }) {
Grid() {
ForEach(this.Number, (day: string) => {
ForEach(this.Number, (day: string) => {
GridItem() {
Text(day)
.fontSize(16)
.backgroundColor(0xF9CF93)
.width('100%')
.height('100%')
.textAlign(TextAlign.Center)
}
}, day => day)
}, day => day)
}
.columnsTemplate('1fr 1fr 1fr 1fr 1fr')
.rowsTemplate('1fr 1fr 1fr 1fr 1fr')
.columnsGap(10)
.rowsGap(10)
.width('90%')
.backgroundColor(0xFAEEE0)
.height(300)
Text('scroll').fontColor(0xCCCCCC).fontSize(9).width('90%')
Grid(this.scroller) {
ForEach(this.Number, (day: string) => {
ForEach(this.Number, (day: string) => {
GridItem() {
Text(day)
.fontSize(16)
.backgroundColor(0xF9CF93)
.width('100%')
.height(80)
.textAlign(TextAlign.Center)
}
}, day => day)
}, day => day)
}
.columnsTemplate('1fr 1fr 1fr 1fr 1fr')
.columnsGap(10)
.rowsGap(10)
.onScrollIndex((first: number) => {
console.info(first.toString())
})
.width('90%')
.backgroundColor(0xFAEEE0)
.height(300)
Button('next page')
.onClick(() => { // 点击后滑到下一页
this.scroller.scrollPage({ next: true })
})
}.width('100%').margin({ top: 5 })
}
}