HarmonyOS API:容器组件

joytrian
发布于 2023-3-24 16:47
浏览
0收藏

版本: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 })
  }
}

HarmonyOS API:容器组件-鸿蒙开发者社区

Grid

更新时间: 2023-02-17 09:19


网格容器,由“行”和“列”分割的单元格所组成,通过指定“项目”所在的单元格做出各种各样的布局。


说明

该组件从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。

子组件

包含​​GridItem​​子组件。

接口

Grid(scroller?: 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​

设置滚动条状态。

默认值: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 })
  }
}

HarmonyOS API:容器组件-鸿蒙开发者社区

文章转载自:​​https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-container-grid-0000001478341161-V3?catalogVersion=V3​

已于2023-3-24 16:47:38修改
收藏
回复
举报
回复
    相关推荐