1# GridItem 2 3The **GridItem** component provides a single item in a grid. 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> * This component can be used only as a child of [Grid](ts-container-grid.md). 9> * When this component is used with **LazyForEach**, its child components are created when it is created. When this component is used with **if/else** or **ForEach**, or when the parent component is **Grid**, its child components are created when it is laid out. 10> * If a **Grid** container contains a large number of **GridItem** components, using **columnStart/columnEnd** or **rowStart/rowEnd** to set the size of **GridItem** components can lead to performance issues, especially when **scrollToIndex** is used to scroll to a specific index. This is because the **Grid** will traverse all **GridItem** nodes sequentially to find the specified index, which can be time-consuming. To address this issue, it is recommended that you use **GridLayoutOptions** for layout, which significantly improves the efficiency of finding the position of **GridItem** components. For best practices, see [Optimizing Frame Loss for Grid Component Loading](https://developer.huawei.com/consumer/en/doc/best-practices/bpta-improve_grid_performance). 11 12## Child Components 13 14This component can contain a single child component. 15 16## APIs 17 18GridItem(value?: GridItemOptions) 19 20Creates a **GridItem** component. 21 22**Atomic service API**: This API can be used in atomic services since API version 11. 23 24**System capability**: SystemCapability.ArkUI.ArkUI.Full 25 26**Parameters** 27 28| Name| Type | Mandatory| Description | 29| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 30| value<sup>11+</sup> | [GridItemOptions](#griditemoptions11) | No | Parameters of the grid item, containing the **style** parameter of the [GridItemStyle](#griditemstyle11) enum type.| 31 32## Attributes 33 34### rowStart 35 36rowStart(value: number) 37 38Sets the start row number of the component. 39 40**Atomic service API**: This API can be used in atomic services since API version 11. 41 42**System capability**: SystemCapability.ArkUI.ArkUI.Full 43 44**Parameters** 45 46| Name| Type | Mandatory| Description | 47| ------ | ------ | ---- | ------------------ | 48| value | number | Yes | Start row number of the component.<br>In situations where you need to designate the start row and column numbers as well as the number of rows and columns a grid item spans, you are advised to use the [layoutOptions parameter](ts-container-grid.md#gridlayoutoptions10) of the **Grid** component. For reference, see [Grid Example 1](ts-container-grid.md#example-1-creating-a-fixed-row-and-column-grid-layout) and [Grid Example 3](ts-container-grid.md#example-3-implementing-a-scrollable-grid-with-grid-items-spanning-rows-and-columns).<br>Value range: [0, Total number of rows – 1].| 49 50### rowEnd 51 52rowEnd(value: number) 53 54Sets the end row number of the component. 55 56**Atomic service API**: This API can be used in atomic services since API version 11. 57 58**System capability**: SystemCapability.ArkUI.ArkUI.Full 59 60**Parameters** 61 62| Name| Type | Mandatory| Description | 63| ------ | ------ | ---- | ------------------ | 64| value | number | Yes | End row number of the component.<br>In situations where you need to designate the start row and column numbers as well as the number of rows and columns a grid item spans, you are advised to use the [layoutOptions parameter](ts-container-grid.md#gridlayoutoptions10) of the **Grid** component. For reference, see [Grid Example 1](ts-container-grid.md#example-1-creating-a-fixed-row-and-column-grid-layout) and [Grid Example 3](ts-container-grid.md#example-3-implementing-a-scrollable-grid-with-grid-items-spanning-rows-and-columns).<br>Value range: [0, Total number of rows – 1].| 65 66### columnStart 67 68columnStart(value: number) 69 70Sets the start column number of the component. 71 72**Atomic service API**: This API can be used in atomic services since API version 11. 73 74**System capability**: SystemCapability.ArkUI.ArkUI.Full 75 76**Parameters** 77 78| Name| Type | Mandatory| Description | 79| ------ | ------ | ---- | ------------------ | 80| value | number | Yes | Start column number of the component.<br>In situations where you need to designate the start row and column numbers as well as the number of rows and columns a grid item spans, you are advised to use the [layoutOptions parameter](ts-container-grid.md#gridlayoutoptions10) of the **Grid** component. For reference, see [Grid Example 1](ts-container-grid.md#example-1-creating-a-fixed-row-and-column-grid-layout) and [Grid Example 3](ts-container-grid.md#example-3-implementing-a-scrollable-grid-with-grid-items-spanning-rows-and-columns).<br>Value range: [0, Total number of columns – 1].| 81 82### columnEnd 83 84columnEnd(value: number) 85 86Sets the end column number of the component. 87 88**Atomic service API**: This API can be used in atomic services since API version 11. 89 90**System capability**: SystemCapability.ArkUI.ArkUI.Full 91 92**Parameters** 93 94| Name| Type | Mandatory| Description | 95| ------ | ------ | ---- | ------------------ | 96| value | number | Yes | End column number of the component.<br>In situations where you need to designate the start row and column numbers as well as the number of rows and columns a grid item spans, you are advised to use the [layoutOptions parameter](ts-container-grid.md#gridlayoutoptions10) of the **Grid** component. For reference, see [Grid Example 1](ts-container-grid.md#example-1-creating-a-fixed-row-and-column-grid-layout) and [Grid Example 3](ts-container-grid.md#example-3-implementing-a-scrollable-grid-with-grid-items-spanning-rows-and-columns).<br>Value range: [0, Total number of columns – 1].| 97 98> **NOTE** 99> 100> In situations where you need to designate the start row and column numbers as well as the number of rows and columns a grid item spans, you are advised to use the [layoutOptions parameter](ts-container-grid.md#gridlayoutoptions10) of the **Grid** component. For reference, see [Grid Example 1](ts-container-grid.md#example-1-creating-a-fixed-row-and-column-grid-layout) and [Grid Example 3](ts-container-grid.md#example-3-implementing-a-scrollable-grid-with-grid-items-spanning-rows-and-columns). 101> 102> Rules for setting **rowStart**, **rowEnd**, **columnStart**, and **columnEnd**: 103> 104> * The valid value range of **rowStart** and **rowEnd** is 0 to the total number of rows minus 1. The valid value range of **columnStart** and **columnEnd** is 0 to the total number of columns minus 1. 105> 106> * If **rowStart**, **rowEnd**, **columnStart**, or **columnEnd** is set, the grid item occupies the specified number of rows (**rowEnd** - **rowStart** + 1) or columns (**columnEnd** - **columnStart** + 1). 107> 108> * Settings outside of the valid ranges do not take effect. 109> 110> * In the grid that has both **columnTemplate** and **rowTemplate** set, grid items that have **rowStart**/**rowEnd** or **columnStart**/**columnEnd** set are laid out in a row-by-row then column-by-column manner. 111> 112> * In the grid that has only **columnTemplate** set, grid items that have **columnStart**/**columnEnd** set are laid out in the specified columns. If there are already grid items in those columns, the grid items will be laid out in another row. 113> 114> * In the grid that has only **rowTemplate** set, grid items that have **rowStart**/**rowEnd** set are laid out on the specified rows. If there are already grid items in those rows, the grid items will be laid out in another column. 115> 116> * In the grid that has neither **columnTemplate** nor **rowTemplate** set, the row and column number attributes do not work. 117> 118> The following table describes the rules for handling abnormal values for **GridItem** row and column numbers. 119> 120> | Attribute Setting | Exception Type | Correction Applied | 121> | ----- |----| ------------------------ | 122> | Only **columnTemplate** set | Invalid row or column value | Single-row and single-column layout | | 123> | Only **rowTemplate** set | Invalid row or column value | Single-row and single-column layout | | 124> | Both **rowTemplate** and **columnTemplate** set | **rowStart** < **rowEnd** | Row span = min(rowEnd-rowStart+1, total number of rows) | 125> | Both **rowTemplate** and **columnTemplate** set | **rowStart** > **rowEnd** | Single-row and single-column layout | 126> | Both **rowTemplate** and **columnTemplate** set | **columnStart** < **columnEnd** | Column span = min(columnEnd-columnStart+1, total number of rows), total number of columns) | 127> | Both **rowTemplate** and **columnTemplate** set | **columnStart** > **columnEnd** | Single-row and single-column layout | 128 129### forceRebuild<sup>(deprecated)</sup> 130 131forceRebuild(value: boolean) 132 133Whether to re-create the component when it is being built. Whether to re-create the component is automatically determined based on the component attributes and child component changes. No manual configuration is required. 134 135This API is deprecated since API version 9. 136 137**System capability**: SystemCapability.ArkUI.ArkUI.Full 138 139**Parameters** 140 141| Name| Type | Mandatory| Description | 142| ------ | ------- | ---- | ------------------------------------------------------- | 143| value | boolean | Yes | Sets whether to re-create the component when it is being built.<br>Default value: **false**| 144 145### selectable<sup>8+</sup> 146 147selectable(value: boolean) 148 149Sets whether the grid item is selectable in the mouse selection box area. This attribute takes effect only when mouse box selection is enabled for the parent **Grid** container. 150 151This attribute must be used before the [style for the selected state](./ts-universal-attributes-polymorphic-style.md#statestyles) is set. Otherwise, the style settings will not take effect. 152 153**Atomic service API**: This API can be used in atomic services since API version 11. 154 155**System capability**: SystemCapability.ArkUI.ArkUI.Full 156 157**Parameters** 158 159| Name| Type | Mandatory| Description | 160| ------ | ------- | ---- | ----------------------------------------------------- | 161| value | boolean | Yes | Whether the grid item is selectable in the mouse selection box area. The **value** means that the grid item is selectable in the mouse selection box area, and **false** means the opposite.<br>Default value: **true**.| 162 163### selected<sup>10+</sup> 164 165selected(value: boolean) 166 167Sets whether the grid item is selected. This attribute supports two-way binding through [$$](../../../ui/state-management/arkts-two-way-sync.md). 168 169This attribute must be used before the [style for the selected state](./ts-universal-attributes-polymorphic-style.md#statestyles) is set. Otherwise, the style settings will not take effect. 170 171**Atomic service API**: This API can be used in atomic services since API version 11. 172 173**System capability**: SystemCapability.ArkUI.ArkUI.Full 174 175**Parameters** 176 177| Name| Type | Mandatory| Description | 178| ------ | ------- | ---- | ---------------------------------------- | 179| value | boolean | Yes | Whether the grid item is selected. The **value** means that the grid item is selected, and **false** means that the grid item is in the default state.<br>Default value: **false**.| 180 181## GridItemOptions<sup>11+</sup> 182 183Defines the style of a grid item. 184 185**Atomic service API**: This API can be used in atomic services since API version 12. 186 187**System capability**: SystemCapability.ArkUI.ArkUI.Full 188 189| Name | Type | Mandatory| Description | 190| ----- | -------------------- | ---- | ---------------------------- | 191| style | [GridItemStyle](#griditemstyle11) | No | Style of the grid item.<br>Default value: **GridItemStyle.NONE**.<br>If this parameter is set to **GridItemStyle.NONE**, no style is applied.<br>If this parameter is set to **GridItemStyle.PLAIN**, the grid item is in hover or press style depending on the state.| 192 193## GridItemStyle<sup>11+</sup> 194 195Enumerates styles of grid items. 196 197**Atomic service API**: This API can be used in atomic services since API version 12. 198 199**System capability**: SystemCapability.ArkUI.ArkUI.Full 200 201| Name |Value| Description | 202| ----- |----| ------------------------ | 203| NONE | 0 | No style. | 204| PLAIN | 1 | Hover or press style.| 205 206> **NOTE** 207> 208> To set the focused style for the grid item, the grid container must have paddings of greater than 4 vp for accommodating the focus frame of the grid item. 209 210## Events 211 212### onSelect<sup>8+</sup> 213 214onSelect(event: (isSelected: boolean) => void) 215 216Triggered when the selected state of the grid item changes. 217 218**Atomic service API**: This API can be used in atomic services since API version 11. 219 220**System capability**: SystemCapability.ArkUI.ArkUI.Full 221 222**Parameters** 223 224| Name | Type | Mandatory| Description | 225| ---------- | ------- | ---- | ------------------------------------------------------------ | 226| isSelected | boolean | Yes | Returns **true** if the grid item is selected in the mouse selection box area; returns **false** otherwise.| 227 228## Example 229 230### Example 1: Setting the Grid Item Position 231This example shows how to set the grid item position using **ColumnStart**, **ColumnEnd**, **RowStart**, and **RowEnd**. In situations where you need to designate the start row and column numbers as well as the number of rows and columns a grid item spans, you are advised to use the [layoutOptions parameter](ts-container-grid.md#gridlayoutoptions10) of the **Grid** component. For reference, see [Grid Example 1](ts-container-grid.md#example-1-creating-a-fixed-row-and-column-grid-layout) and [Grid Example 3](ts-container-grid.md#example-3-implementing-a-scrollable-grid-with-grid-items-spanning-rows-and-columns). 232 233```ts 234// xxx.ets 235@Entry 236@Component 237struct GridItemExample { 238 @State numbers: string[] = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15"]; 239 240 build() { 241 Column() { 242 Grid() { 243 GridItem() { 244 Text('4') 245 .fontSize(16) 246 .backgroundColor(0xFAEEE0) 247 .width('100%') 248 .height('100%') 249 .textAlign(TextAlign.Center) 250 }.rowStart(1).rowEnd(2).columnStart(1).columnEnd(2) // Set valid row and column numbers. 251 252 ForEach(this.numbers, (item: string) => { 253 GridItem() { 254 Text(item) 255 .fontSize(16) 256 .backgroundColor(0xF9CF93) 257 .width('100%') 258 .height('100%') 259 .textAlign(TextAlign.Center) 260 } 261 }, (item: string) => item) 262 263 GridItem() { 264 Text('5') 265 .fontSize(16) 266 .backgroundColor(0xDBD0C0) 267 .width('100%') 268 .height('100%') 269 .textAlign(TextAlign.Center) 270 }.columnStart(1).columnEnd(4) // Set only the column numbers. The layout does not start from the first column. 271 } 272 .columnsTemplate('1fr 1fr 1fr 1fr 1fr') 273 .rowsTemplate('1fr 1fr 1fr 1fr 1fr') 274 .width('90%').height(300) 275 }.width('100%').margin({ top: 5 }) 276 } 277} 278``` 279 280 281 282### Example 2: Setting the Grid Item Style 283 284This example shows how to set the grid item style using **GridItemOptions**. 285 286```ts 287// xxx.ets 288@Entry 289@Component 290struct GridItemExample { 291 @State numbers: String[] = ['0', '1', '2']; 292 293 build() { 294 Column({ space: 5 }) { 295 Grid() { 296 ForEach(this.numbers, (day: string) => { 297 ForEach(this.numbers, (day: string) => { 298 GridItem({style:GridItemStyle.NONE}) { 299 Text(day) 300 .fontSize(16) 301 .width('100%') 302 .height('100%') 303 .textAlign(TextAlign.Center) 304 .focusable(true) 305 } 306 .backgroundColor(0xF9CF93) 307 }, (day: string) => day) 308 }, (day: string) => day) 309 } 310 .columnsTemplate('1fr 1fr 1fr') 311 .rowsTemplate('1fr 1fr') 312 .columnsGap(4) 313 .rowsGap(4) 314 .width('60%') 315 .backgroundColor(0xFAEEE0) 316 .height(150) 317 .padding('4vp') 318 319 Grid() { 320 ForEach(this.numbers, (day: string) => { 321 ForEach(this.numbers, (day: string) => { 322 GridItem({style:GridItemStyle.PLAIN}) { 323 Text(day) 324 .fontSize(16) 325 .width('100%') 326 .height('100%') 327 .textAlign(TextAlign.Center) 328 .focusable(true) 329 } 330 .backgroundColor(0xF9CF93) 331 }, (day: string) => day) 332 }, (day: string) => day) 333 } 334 .columnsTemplate('1fr 1fr 1fr') 335 .rowsTemplate('1fr 1fr') 336 .columnsGap(4) 337 .rowsGap(4) 338 .width('60%') 339 .backgroundColor(0xFAEEE0) 340 .height(150) 341 .padding('4vp') 342 }.width('100%').margin({ top: 5 }) 343 } 344} 345``` 346 347 348
