1# Grid 2 3The **\<Grid>** component consists of cells formed by rows and columns. You can specify the cells where items are located to form various layouts. 4 5> **NOTE** 6> 7> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Child Components 11 12This component contains the child component **[\<GridItem>](ts-container-griditem.md)**. 13 14 15## APIs 16 17Grid(scroller?: Scroller) 18 19**Parameters** 20| Name | Type | Mandatory | Description | 21| --------- | ---------------------------------------- | ---- | ----------------------- | 22| scroller | [Scroller](ts-container-scroll.md#scroller) | No | Scroller, which can be bound to scrollable components.| 23 24## Attributes 25 26In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 27 28| Name| Type| Description| 29| -------- | -------- | -------- | 30| 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.| 31| 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.| 32| columnsGap | Length | Gap between columns.<br>Default value: **0**| 33| rowsGap | Length | Gap between rows.<br>Default value: **0**| 34| scrollBar | [BarState](ts-appendix-enums.md#barstate) | Scrollbar status.<br>Default value: **BarState.Off**| 35| scrollBarColor | string \| number \| Color | Color of the scrollbar.| 36| scrollBarWidth | string \| number | Width of the scrollbar.| 37| cachedCount | number | Number of grid items to be preloaded. For details, see [Minimizing White Blocks During Swiping](../../ui/ui-ts-performance-improvement-recommendation.md#minimizing-white-blocks-during-swiping).<br>Default value: **1**| 38| 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** | 39| layoutDirection<sup>8+</sup> | [GridDirection](#griddirection8) | Main axis direction of the grid.<br>Default value: **GridDirection.Row**| 40| maxCount<sup>8+</sup> | number | When **layoutDirection** is **Row** or **RowReverse**: maximum number of columns that can be displayed.<br>When **layoutDirection** is **Column** or **ColumnReverse**: maximum number of rows that can be displayed.<br>Default value: **Infinity**| 41| minCount<sup>8+</sup> | number | When **layoutDirection** is **Row** or **RowReverse**: minimum number of columns that can be displayed.<br>When **layoutDirection** is **Column** or **ColumnReverse**: maximum number of rows that can be displayed.<br>Default value: **1**| 42| 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: size of the first element| 43| 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.| 44| supportAnimation<sup>8+</sup> | boolean | Whether to enable animation.<br>Default value: **false**| 45 46Depending on the settings of the **rowsTemplate** and **columnsTemplate** attributes, the **\<Grid>** component supports the following layout modes: 47 481. **rowsTemplate** and **columnsTemplate** are both set 49 50 The **\<Grid>** displays only elements in a fixed number of rows and columns and cannot be scrolled. For example, if both **rowsTemplate** and **columnsTemplate** are set to **"1fr 1fr"**, only four elements (two rows and two columns) are displayed. 51 52 In this mode, the following attributes do not take effect: **layoutDirection**, **maxCount**, minCount, and **cellLength**. 53 542. Either **rowsTemplate** or **columnsTemplate** is set 55 56 The **\<Grid>** arranges elements in the specified direction and allows for scrolling to display excess elements. For example, if the **\<Grid>** has 10 elements and **columnsTemplate** is set to **"1fr 1fr 1fr"**, it contains three columns. The elements are arranged in the same direction as the main axis runs down the columns. Elements outside the **\<Grid>** area can be viewed through scrolling. 57 58 In this mode, the following attributes do not take effect: **layoutDirection**, **maxCount**, **minCount**, and **cellLength**. 59 603. Neither **rowsTemplate** nor **columnsTemplate** is set 61 62 The **\<Grid>** arranges elements in the direction specified by **layoutDirection **. The number of columns is jointly determined by the grid width, width of the first element, **minCount**, **maxCount**, and **columnsGap**. The number of rows is jointly determined by the grid height, height of the first element, **cellLength**, and **rowsGap**. Elements outside the determined range of rows and columns are not displayed and cannot be viewed through scrolling. 63 64 In this mode, only the following attributes take effect: **layoutDirection**, **maxCount**, **minCount**, **cellLength**, **editMode**, **columnsGap**, and **rowsGap**. 65 66## GridDirection<sup>8+</sup> 67 68| Name | Description | 69| ------ | -------------------------------------- | 70| Row | Horizontal layout, where the child components are arranged from left to right as the main axis runs along the rows.| 71| Column | Vertical layout, where the child components are arranged from top to bottom as the main axis runs down the columns.| 72| RowReverse | Reverse horizontal layout, where the child components are arranged from right to left as the main axis runs along the rows.| 73| ColumnReverse | Reverse vertical layout, where the child components are arranged from bottom up as the main axis runs down the columns.| 74 75## Events 76 77In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 78 79| Name| Description| 80| -------- | -------- | 81| onScrollIndex(event: (first: number) => void) | Triggered when the start item of the grid changes.<br>- **first**: index of the start item of the grid.| 82| 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.| 83| onItemDragEnter(event: (event: ItemDragInfo) => void) | Triggered when the dragged item enters the drop target of the grid.<br>- **event**: See [ItemDragInfo](#itemdraginfo).| 84| 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.| 85| 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.| 86| 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.| 87 88## ItemDragInfo 89 90| Name | Type | Description | 91| ---------- | ---------- | ---------- | 92| x | number | X-coordinate of the dragged item. | 93| y | number | Y-coordinate of the dragged item. | 94 95## Example 96 97```ts 98// xxx.ets 99@Entry 100@Component 101struct GridExample { 102 @State Number: String[] = ['0', '1', '2', '3', '4'] 103 scroller: Scroller = new Scroller() 104 105 build() { 106 Column({ space: 5 }) { 107 Grid() { 108 ForEach(this.Number, (day: string) => { 109 ForEach(this.Number, (day: string) => { 110 GridItem() { 111 Text(day) 112 .fontSize(16) 113 .backgroundColor(0xF9CF93) 114 .width('100%') 115 .height('100%') 116 .textAlign(TextAlign.Center) 117 } 118 }, day => day) 119 }, day => day) 120 } 121 .columnsTemplate('1fr 1fr 1fr 1fr 1fr') 122 .rowsTemplate('1fr 1fr 1fr 1fr 1fr') 123 .columnsGap(10) 124 .rowsGap(10) 125 .width('90%') 126 .backgroundColor(0xFAEEE0) 127 .height(300) 128 129 Text('scroll').fontColor(0xCCCCCC).fontSize(9).width('90%') 130 Grid(this.scroller) { 131 ForEach(this.Number, (day: string) => { 132 ForEach(this.Number, (day: string) => { 133 GridItem() { 134 Text(day) 135 .fontSize(16) 136 .backgroundColor(0xF9CF93) 137 .width('100%') 138 .height(80) 139 .textAlign(TextAlign.Center) 140 } 141 }, day => day) 142 }, day => day) 143 } 144 .columnsTemplate('1fr 1fr 1fr 1fr 1fr') 145 .columnsGap(10) 146 .rowsGap(10) 147 .onScrollIndex((first: number) => { 148 console.info(first.toString()) 149 }) 150 .width('90%') 151 .backgroundColor(0xFAEEE0) 152 .height(300) 153 Button('next page') 154 .onClick(() => {// Click to go to the next page. 155 this.scroller.scrollPage({ next: true }) 156 }) 157 }.width('100%').margin({ top: 5 }) 158 } 159} 160``` 161 162 163
