Grid

網(wǎng)格容器，由“行”和“列”分割的單元格所組成，通過(guò)指定“項(xiàng)目”所在的單元格做出各種各樣的布局。

說(shuō)明：
開(kāi)發(fā)前請(qǐng)熟悉鴻蒙開(kāi)發(fā)指導(dǎo)文檔 ：[复制gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]
該組件從API Version 7開(kāi)始支持。后續(xù)版本如有新增內(nèi)容，則采用上角標(biāo)單獨(dú)標(biāo)記該內(nèi)容的起始版本。

子組件

僅支持[GridItem]子組件。

說(shuō)明：

Grid子組件的索引值計(jì)算規(guī)則：

按子組件的順序依次遞增。

if/else語(yǔ)句中，只有條件成立分支內(nèi)的子組件會(huì)參與索引值計(jì)算，條件不成立分支內(nèi)的子組件不計(jì)算索引值。

ForEach/LazyForEach語(yǔ)句中，會(huì)計(jì)算展開(kāi)所有子節(jié)點(diǎn)索引值。

[if/else]、[ForEach]和[LazyForEach]發(fā)生變化以后，會(huì)更新子節(jié)點(diǎn)索引值。

Grid子組件的visibility屬性設(shè)置為Hidden或None時(shí)依然會(huì)計(jì)算索引值。

Grid子組件的visibility屬性設(shè)置為None時(shí)不顯示，但依然會(huì)占用子組件對(duì)應(yīng)的網(wǎng)格。

Grid子組件設(shè)置position屬性，會(huì)占用子組件對(duì)應(yīng)的網(wǎng)格，子組件將顯示在相對(duì)Grid左上角偏移position的位置。該子組件不會(huì)隨其對(duì)應(yīng)網(wǎng)格滾動(dòng)，在對(duì)應(yīng)網(wǎng)格滑出Grid顯示范圍外后不顯示。

接口

Grid(scroller?: Scroller, layoutOptions?: GridLayoutOptions)

參數(shù)：

GridLayoutOptions10+

布局選項(xiàng)，配合rowsTemplate、columnsTemplate僅設(shè)置其中一個(gè)的Grid使用，可以替代通過(guò)columnStart/columnEnd控制GridItem占用多列、rowStart/rowEnd控制GridItem占用多行的場(chǎng)景。

參數(shù)：

屬性

除支持[通用屬性]外，還支持以下屬性：

Grid組件根據(jù)rowsTemplate、columnsTemplate屬性的設(shè)置情況，可分為以下三種布局模式：

1、rowsTemplate、columnsTemplate同時(shí)設(shè)置：

• Grid只展示固定行列數(shù)的元素，其余元素不展示，且Grid不可滾動(dòng)。
• 此模式下以下屬性不生效：layoutDirection、maxCount、minCount、cellLength。
• Grid的寬高沒(méi)有設(shè)置時(shí)，默認(rèn)適應(yīng)父組件尺寸。
• Gird網(wǎng)格列大小按照Gird自身內(nèi)容區(qū)域大小減去所有行列Gap后按各個(gè)行列所占比重分配。
• GridItem默認(rèn)填滿網(wǎng)格大小。

2、rowsTemplate、columnsTemplate僅設(shè)置其中的一個(gè)：

• 元素按照設(shè)置的方向進(jìn)行排布，超出Grid顯示區(qū)域后，Grid可通過(guò)滾動(dòng)的方式展示。
• 如果設(shè)置了columnsTemplate，Gird滾動(dòng)方向?yàn)榇怪狈较?，主軸方向?yàn)榇怪狈较?，交叉軸方向?yàn)樗椒较颉?/li>
• 如果設(shè)置了rowsTemplate，Gird滾動(dòng)方向?yàn)樗椒较颍鬏S方向?yàn)樗椒较?，交叉軸方向?yàn)榇怪狈较颉?/li>
• 此模式下以下屬性不生效：layoutDirection、maxCount、minCount、cellLength。
• 網(wǎng)格交叉軸方向尺寸根據(jù)Gird自身內(nèi)容區(qū)域交叉軸尺寸減去交叉軸方向所有Gap后按所占比重分配。
• 網(wǎng)格主軸方向尺寸取當(dāng)前網(wǎng)格交叉軸方向所有GridItem高度最大值。

3、rowsTemplate、columnsTemplate都不設(shè)置：

• 元素在layoutDirection方向上排布，列數(shù)由Grid的寬度、首個(gè)元素的寬度、minCount、maxCount、columnsGap共同決定。
• 行數(shù)由Grid高度、首個(gè)元素高度、cellLength、rowsGap共同決定。超出行列容納范圍的元素不顯示，也不能通過(guò)滾動(dòng)進(jìn)行展示。
• 此模式下僅生效以下屬性：layoutDirection、maxCount、minCount、cellLength、editMode、columnsGap、rowsGap。
• 當(dāng)前l(fā)ayoutDirection設(shè)置為Row時(shí)，先從左到右排列，排滿一行再排一下一列。剩余高度不足時(shí)不再布局，整體內(nèi)容頂部居中。
• 當(dāng)前l(fā)ayoutDirection設(shè)置為Column時(shí)，先從上到下排列，排滿一列再排一下一列，剩余寬度度不足時(shí)不再。整體內(nèi)容頂部居中。

GridDirection8+枚舉說(shuō)明

說(shuō)明：

Grid組件[通用屬性clip]的默認(rèn)值為true。

事件

除支持[通用事件]外，還支持以下事件：

ItemDragInfo對(duì)象說(shuō)明

ComputedBarAttribute對(duì)象說(shuō)明

示例

示例1

复制// 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: string) = > day)
        }, (day: string) = > 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: string) = > day)
        }, (day: string) = > day)
      }
      .columnsTemplate('1fr 1fr 1fr 1fr 1fr')
      .columnsGap(10)
      .rowsGap(10)
      .friction(0.6)
      .edgeEffect(EdgeEffect.Spring)
      .scrollBar(BarState.On)
      .onScrollIndex((first: number) = > {
        console.info(first.toString())
      })
      .onScrollBarUpdate((index: number, offset: number) = > {
        return {totalOffset: (index / 5) * (80 + 10) - offset, totalLength: 80 * 5 + 10 * 4}
      })
      .width('90%')
      .backgroundColor(0xFAEEE0)
      .height(300)
      Button('next page')
        .onClick(() = > { // 點(diǎn)擊后滑到下一頁(yè)
          this.scroller.scrollPage({ next: true })
        })
    }.width('100%').margin({ top: 5 })
  }
}

示例2

1. 設(shè)置屬性editMode(true)設(shè)置Grid是否進(jìn)入編輯模式，進(jìn)入編輯模式可以拖拽Grid組件內(nèi)部GridItem。
2. 在[onItemDragStart]回調(diào)中設(shè)置拖拽過(guò)程中顯示的圖片。
3. 在[onItemDrop]中獲取拖拽起始位置，和拖拽插入位置，在[onDrag]回調(diào)中完成交換數(shù)組位置邏輯。

复制@Entry
@Component
struct GridExample {
  @State numbers: string[] = []
  scroller: Scroller = new Scroller()
  @State text: string = 'drag'

  @Builder pixelMapBuilder() { //拖拽過(guò)程樣式
    Column() {
      Text(this.text)
        .fontSize(16)
        .backgroundColor(0xF9CF93)
        .width(80)
        .height(80)
        .textAlign(TextAlign.Center)
    }
  }

  aboutToAppear() {
    for (let i = 1;i <= 15; i++) {
      this.numbers.push(i + '')
    }
  }

  changeIndex(index1: number, index2: number) { //交換數(shù)組位置
    let temp: string;
    temp = this.numbers[index1];
    this.numbers[index1] = this.numbers[index2];
    this.numbers[index2] = temp;
  }

  build() {
    Column({ space: 5 }) {
      Grid(this.scroller) {
        ForEach(this.numbers, (day: string) = > {
          GridItem() {
            Text(day)
              .fontSize(16)
              .backgroundColor(0xF9CF93)
              .width(80)
              .height(80)
              .textAlign(TextAlign.Center)
          }
        })
      }
      .columnsTemplate('1fr 1fr 1fr')
      .columnsGap(10)
      .rowsGap(10)
      .onScrollIndex((first: number) = > {
        console.info(first.toString())
      })
      .width('90%')
      .backgroundColor(0xFAEEE0)
      .height(300)
      .editMode(true) //設(shè)置Grid是否進(jìn)入編輯模式，進(jìn)入編輯模式可以拖拽Grid組件內(nèi)部GridItem
      .onItemDragStart((event: ItemDragInfo, itemIndex: number) = > { //第一次拖拽此事件綁定的組件時(shí)，觸發(fā)回調(diào)。
        this.text = this.numbers[itemIndex]
        return this.pixelMapBuilder() //設(shè)置拖拽過(guò)程中顯示的圖片。
      })
      .onItemDrop((event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) = > { //綁定此事件的組件可作為拖拽釋放目標(biāo)，當(dāng)在本組件范圍內(nèi)停止拖拽行為時(shí)，觸發(fā)回調(diào)。
        // isSuccess=false時(shí)，說(shuō)明drop的位置在grid外部；insertIndex > length時(shí)，說(shuō)明有新增元素的事件發(fā)生
        if (!isSuccess || insertIndex >= this.numbers.length) {
          return
        }
        console.info('beixiang' + itemIndex + '', insertIndex + '') //itemIndex拖拽起始位置，insertIndex拖拽插入位置
        this.changeIndex(itemIndex, insertIndex)
      })
    }.width('100%').margin({ top: 5 })
  }
}

示例圖：

網(wǎng)格子組件開(kāi)始拖拽：

網(wǎng)格子組件拖拽過(guò)程中：

網(wǎng)格子組件1與子組件6拖拽交換位置后：

示例3

使用GridLayoutOptions

复制// xxx.ets
@Entry
@Component
struct GridExample {
  @State Number: String[] = ['0', '1', '2', '3', '4']
  scroller: Scroller = new Scroller()
  layoutOptions1: GridLayoutOptions = {
    regularSize: [1, 1],        // 只支持[1, 1]
    irregularIndexes: [0, 6],   // 索引為0和6的GridItem占用一行
  }

  layoutOptions2: GridLayoutOptions = {
    regularSize: [1, 1],
    irregularIndexes: [0, 7],   // 索引為0和7的GridItem占用的列數(shù)由onGetIrregularSizeByIndex指定
    onGetIrregularSizeByIndex: (index: number) = > {
      if (index === 0) {
        return [1, 5]
      }
      return [1, index % 6 + 1]
    }
  }

  build() {
    Column({ space: 5 }) {
      Grid(this.scroller, this.layoutOptions1) {
        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: string) = > day)
        }, (day: string) = > day)
      }
      .columnsTemplate('1fr 1fr 1fr 1fr 1fr')
      .columnsGap(10)
      .rowsGap(10)
      .scrollBar(BarState.Off)
      .width('90%')
      .backgroundColor(0xFAEEE0)
      .height(300)

      Text('scroll').fontColor(0xCCCCCC).fontSize(9).width('90%')
      // 不使用scroll，需要undefined占位
      Grid(undefined, this.layoutOptions2) {
        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: string) = > day)
        }, (day: string) = > day)
      }
      .columnsTemplate('1fr 1fr 1fr 1fr 1fr')
      .columnsGap(10)
      .rowsGap(10)
      .scrollBar(BarState.Off)
      .width('90%')
      .backgroundColor(0xFAEEE0)
      .height(300)
    }.width('100%').margin({ top: 5 })
  }
}

審核編輯 黃宇