ts-container-grid.md 9.6 KB
Newer Older
Z
zengyawen 已提交
1
# Grid
Z
zengyawen 已提交
2

E
ester.zhou 已提交
3 4
The **\<Grid>** component consists of cells formed by rows and columns. You can specify the cells where items are located to form various layouts.

E
ester.zhou 已提交
5
>  **NOTE**
E
ester.zhou 已提交
6
>
E
ester.zhou 已提交
7 8
>  This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.

Z
zengyawen 已提交
9 10 11

## Child Components

E
ester.zhou 已提交
12
This component contains the child component **[\<GridItem>](ts-container-griditem.md)**.
Z
zengyawen 已提交
13 14


E
ester.zhou 已提交
15
## Interface
E
ester.zhou 已提交
16

E
ester.zhou 已提交
17
Grid(scroller?: Scroller)
Z
zengyawen 已提交
18

E
ester.zhou 已提交
19 20 21 22
**Parameters**
| Name      | Type                                    | Mandatory  | Description                   |
| --------- | ---------------------------------------- | ---- | ----------------------- |
| scroller  | [Scroller](ts-container-scroll.md#scroller) | No   | Scroller, which can be bound to scrollable components.|
Z
zengyawen 已提交
23 24 25

## Attributes

E
ester.zhou 已提交
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.

| Name| Type| Description|
| -------- | -------- | -------- |
| columnsTemplate | string | Number of columns in the current grid layout. If this attribute is not set, one column is used by default.<br>For example, **'1fr 1fr 2fr'** indicates three columns, with the first column taking up 1/4 of the parent component's full width, the second column 1/4, and the third column 2/4. This attribute supports [auto-fill] (#auto-fill description).<br>Default value: **'1fr'**|
| rowsTemplate | string | Number of rows in the current grid layout. If this attribute is not set, one row is used by default.<br>For example, **'1fr 1fr 2fr'** indicates three rows, with the first row taking up 1/4 of the parent component's full height, the second row 1/4, and the third row 2/4. This attribute supports [auto-fill] (#auto-fill description).<br>Default value: **'1fr'**|
| columnsGap | Length | Gap between columns.<br>Default value: **0**|
| rowsGap | Length | Gap between rows.<br>Default value: **0**|
| scrollBar      | [BarState](ts-appendix-enums.md#barstate) | Scrollbar status.<br>Default value: **BarState.Off**|
| scrollBarColor | string \| number \| Color              | Color of the scrollbar.|
| scrollBarWidth | string \| number    | Width of the scrollbar.|
| cachedCount | number                                   | Number of grid items to be preloaded. For details, see [Minimizing White Blocks During Swiping](../../ui/ts-performance-improvement-recommendation.md#minimizing-white-blocks-during-swiping).<br>Default value: **1**|
| editMode <sup>8+</sup>                   | boolean | Whether to enter editing mode. In editing mode, the user can drag the **\<[GridItem](ts-container-griditem.md)>** in the **\<Grid>** component.<br>Default value: **false**|
| layoutDirection<sup>8+</sup>             | [GridDirection](#griddirection8) | Main axis direction of the grid.<br>Default value: **GridDirection.Row**|
| maxCount<sup>8+</sup> | number  | When **layoutDirection** is **Row** or **RowReverse**: maximum number of rows that can be displayed.<br>When **layoutDirection** is **Column** or **ColumnReverse**: maximum number of columns that can be displayed.<br>Default value: **1**|
| minCount<sup>8+</sup> | number  | When **layoutDirection** is **Row** or **RowReverse**: minimum number of rows that can be displayed.<br>When **layoutDirection** is **Column** or **ColumnReverse**: minimum number of columns that can be displayed.<br>Default value: **1**|
| cellLength<sup>8+</sup> | number  | When **layoutDirection** is **Row** or **RowReverse**: fixed height per row.<br>When **layoutDirection** is **Column** or **ColumnReverse**: fixed width per column.<br>Default value: **0**|
| multiSelectable<sup>8+</sup> | boolean | Whether to enable mouse frame selection.<br>Default value: **false**<br>- **false**: The mouse frame selection is disabled.<br>- **true**: The mouse frame selection is enabled.|
| supportAnimation<sup>8+</sup> | boolean | Whether to enable animation.<br>Default value: **false**|

## GridDirection<sup>8+</sup>

| Name  | Description                                  |
  | ------ | -------------------------------------- |
| Row  | Horizontal layout, where the child components are arranged from left to right as the main axis runs along the rows.|
| Column | Vertical layout, where the child components are arranged from top to bottom as the main axis runs down the columns.|
| RowReverse    | Reverse horizontal layout, where the child components are arranged from right to left as the main axis runs along the rows.|
| ColumnReverse   | Reverse vertical layout, where the child components are arranged from bottom up as the main axis runs down the columns.|
Z
zengyawen 已提交
54 55 56

## Events

E
ester.zhou 已提交
57 58
In addition to the [universal events](ts-universal-events-click.md), the following events are supported.

E
ester.zhou 已提交
59
| Name| Description|
Z
zengyawen 已提交
60
| -------- | -------- |
E
ester.zhou 已提交
61 62 63 64 65 66 67 68 69 70 71 72 73 74
| onScrollIndex(event: (first: number) => void) | Triggered when the start item of the grid changes.<br>- **first**: index of the start item of the grid.|
| onItemDragStart(event: (event: ItemDragInfo, itemIndex: number) => (() => any) \| void) | Triggered when a grid item starts to be dragged.<br>- **event**: See [ItemDragInfo](#itemdraginfo).<br>- **itemIndex**: index of the dragged element.|
| onItemDragEnter(event: (event: ItemDragInfo) => void) | Triggered when the dragged item enters the drop target of the grid.<br>- **event**: See [ItemDragInfo](#itemdraginfo).|
| onItemDragMove(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number) => void) | Triggered when the dragged item moves over the drop target of the grid.<br>- **event**: See [ItemDragInfo](#itemdraginfo).<br>- **itemIndex**: initial position of the dragged item.<br>- **insertIndex**: index of the position to which the dragged item will be dropped.|
| onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void) | Triggered when the dragged item exits the drop target of the grid.<br>- **event**: See [ItemDragInfo](#itemdraginfo).<br>- **itemIndex**: index of the dragged item.|
| onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void) | Triggered when the dragged item is dropped on the drop target of the grid.<br>- **event**: See [ItemDragInfo](#itemdraginfo).<br>- **itemIndex**: initial position of the dragged item.<br>- **insertIndex**: index of the position to which the dragged item will be dropped.<br>- **isSuccess**: whether the dragged item is successfully dropped.|

## Notes About auto-fill

In the **columnsTemplate** and **rowsTemplate** attributes of the **\<Grid>** component, **auto-fill** supports only the following formats:

```css
repeat(auto-fill, track-size)
```
Z
zengyawen 已提交
75

E
ester.zhou 已提交
76 77 78 79 80 81 82 83
The keywords **repeat** and **auto-fill** are used. **track-size** indicates the row height or column width, which can be in the unit of px, vp, %, or valid digits. The value must contain at least one valid row height or column width.

## ItemDragInfo

| Name        | Type        |   Description        |
| ---------- | ---------- | ---------- |
| x | number |  X-coordinate of the dragged item.   |
| y   | number |  Y-coordinate of the dragged item.   |
Z
zengyawen 已提交
84 85 86

## Example

E
ester.zhou 已提交
87 88
```ts
// xxx.ets
Z
zengyawen 已提交
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146
@Entry
@Component
struct GridExample {
  @State Number: String[] = ['0', '1', '2', '3', '4']

  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() {
        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)
    }.width('100%').margin({ top: 5 })
  }
}
```

E
ester.zhou 已提交
147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192
![zh-cn_image_0000001219744183](figures/zh-cn_image_0000001219744183.gif)

**Example of auto-fill**

```ts
// grid-autofill.ets
@Entry
@Component
struct Index {
  @State gridItemWidth: string = "100%"
  @State gridItemHeight: string = "100%"
  @State gridWidth: string = "100%"
  @State gridHeight: string = "100%"
  @State itemList: string[] = []
  build() {
    Column() {
      Grid() {
        ForEach(this.itemList, (item) => {
          GridItem() {
            Text(item.toString())
              .fontSize(16)
              .width('100%')
              .textAlign(TextAlign.Center)
          }
          .width(this.gridItemWidth)
          .height(this.gridItemHeight)
          .backgroundColor(0xF9CF93)
        }, item => item)
      }
      .columnsGap(1)
      .rowsGap(1)
      .border({ width: 4, color: 0xffdb7093, style: BorderStyle.Dashed, radius: 5 })
      .width(this.gridWidth)
      .height(this.gridHeight)
      .columnsTemplate("15% repeat(auto-fill, 10% 50px 20%) 50px")
      .rowsTemplate("150px repeat(auto-fill, 20% 25%)")
    }.margin(5)
  }

  aboutToAppear() {
    for(var i = 1; i < 50; i++) {
      this.itemList.push(i.toString())
    }
  }
}
```
Z
zengyawen 已提交
193

E
ester.zhou 已提交
194
![grid-autofill](figures/grid-autofill.png)