1# GridItem 2 3网格容器中单项内容容器。 4 5> **说明：** 6> 7> * 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> * 仅支持作为[Grid](ts-container-grid.md)组件的子组件使用。 9 10 11## 子组件 12 13可以包含单个子组件。 14 15## 接口 16 17### GridItem 18 19GridItem(value?: GridItemOptions) 20 21**参数：** 22 23| 参数名 | 参数类型 | 必填 | 参数描述 | 24| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 25| value<sup>11+</sup> | [GridItemOptions](#griditemoptions11对象说明) | 否 | 为GridItem提供可选参数, 该对象内含有[GridItemStyle](#griditemstyle11枚举说明)枚举类型的style参数。 | 26 27## 属性 28 29| 名称 | 参数类型 | 描述 | 30| -------- | -------- | -------- | 31| rowStart | number | 指定当前元素起始行号。 | 32| rowEnd | number | 指定当前元素终点行号。 | 33| columnStart | number | 指定当前元素起始列号。 | 34| columnEnd | number | 指定当前元素终点列号。 | 35| forceRebuild<sup>(deprecated)</sup> | boolean | 设置在触发组件build时是否重新创建此节点。<br/>从API version9开始废弃。GridItem会根据自身属性和子组件变化自行决定是否需要重新创建，无需设置。<br/>默认值：false | 36| selectable<sup>8+</sup> | boolean | 当前GridItem元素是否可以被鼠标框选。<br/>> **说明：**<br/>> 外层Grid容器的鼠标框选开启时，GridItem的框选才生效。<br/>默认值：true | 37| selected<sup>10+</sup> | boolean | 设置当前GridItem选中状态。该属性支持[$$](../../../quick-start/arkts-two-way-sync.md)双向绑定变量。<br/>**说明：**<br/>该属性需要在设置[选中态样式](./ts-universal-attributes-polymorphic-style.md#statestyles接口说明)前使用才能生效选中态样式。<br/>默认值：false| 38 39> **说明：** 40> 41> 当Grid配合[LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md)使用时，最后一个GridItem需要限定布局推荐使用[Grid的layoutOptions参数](ts-container-grid.md)，详细可参考[Grid的示例3](ts-container-grid.md#示例3)。 42> 43> 起始行号、终点行号、起始列号、终点列号生效规则如下： 44> 45> rowStart/rowEnd合理取值范围为0\~总行数-1，columnStart/columnEnd合理取值范围为0\~总列数-1。 46> 47> 如果设置了rowStart/rowEnd/columnStart/columnEnd，GridItem会占据指定的行数(rowEnd-rowStart+1)或列数(columnEnd-columnStart+1)。 48> 49> 只有在设置columnTemplate和rowTemplate的Grid中，设置合理的rowStart/rowEnd/columnStart/columnEnd四个属性的GridItem才能按照指定的行列号布局。 50> 51> 在设置columnTemplate和rowTemplate的Grid中，单独设置行号rowStart/rowEnd或列号columnStart/columnEnd的GridItem会按照一行一列进行布局。 52> 53> 在只设置columnTemplate的Grid中设置列号columnStart/columnEnd的GridItem按照列数布局。在该区域位置存在GridItem布局，则直接换行进行放置。 54> 55> 在只设置rowTemplate的Grid中设置行号rowStart/rowEnd的GridItem按照行数布局。在该区域位置存在GridItem布局，则直接换列进行放置。 56> 57> 在只设置columnTemplate的Grid中，在GridItem上设置了不合理的值，GridItem按照一行一列进行布局。 58> 59> columnTemplate和rowTemplate都不设置的Grid中GridItem的行列号属性无效。 60 61## GridItemOptions<sup>11+</sup>对象说明 62 63| 名称 | 参数类型 | 必填 | 描述 | 64| ----- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 65| style | [GridItemStyle](#griditemstyle11枚举说明) | 否 | 设置GridItem样式。<br/>默认值: GridItemStyle.NONE<br/>设置为GridItemStyle.NONE时无样式。<br/>设置为GridItemStyle.PLAIN时，显示Hover、Press态样式。 | 66 67## GridItemStyle<sup>11+</sup>枚举说明 68 69| 名称 |枚举值| 描述 | 70| ----- |----| ------------------------ | 71| NONE | 0 | 无样式。 | 72| PLAIN | 1 | 显示Hover、Press态样式。 | 73 74> **说明：** 75> 76> GridItem焦点态样式设置：Grid组件需要设置4vp规格以上的内边距，用于显示GridItem的焦点框。 77 78 79## 事件 80 81| 名称 | 功能描述 | 82| -------- | -------- | 83| onSelect(event: (isSelected: boolean) => void)<sup>8+</sup> | GridItem元素被鼠标框选的状态改变时触发回调。<br/>isSelected：进入鼠标框选范围即被选中返回true， 移出鼠标框选范围即未被选中返回false。 | 84 85## 示例 86 87### 示例1 88 89```ts 90// xxx.ets 91@Entry 92@Component 93struct GridItemExample { 94 @State numbers: string[] = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15"] 95 96 build() { 97 Column() { 98 Grid() { 99 GridItem() { 100 Text('4') 101 .fontSize(16) 102 .backgroundColor(0xFAEEE0) 103 .width('100%') 104 .height('100%') 105 .textAlign(TextAlign.Center) 106 }.rowStart(1).rowEnd(2).columnStart(1).columnEnd(2) // 同时设置合理的行列号 107 108 ForEach(this.numbers, (item: string) => { 109 GridItem() { 110 Text(item) 111 .fontSize(16) 112 .backgroundColor(0xF9CF93) 113 .width('100%') 114 .height('100%') 115 .textAlign(TextAlign.Center) 116 } 117 }, (item: string) => item) 118 119 GridItem() { 120 Text('5') 121 .fontSize(16) 122 .backgroundColor(0xDBD0C0) 123 .width('100%') 124 .height('100%') 125 .textAlign(TextAlign.Center) 126 }.columnStart(1).columnEnd(4) // 只设置列号，不会从第1列开始布局 127 } 128 .columnsTemplate('1fr 1fr 1fr 1fr 1fr') 129 .rowsTemplate('1fr 1fr 1fr 1fr 1fr') 130 .width('90%').height(300) 131 }.width('100%').margin({ top: 5 }) 132 } 133} 134``` 135 136 137 138### 示例2 139 140使用GridItemOptions 141 142```ts 143// xxx.ets 144@Entry 145@Component 146struct GridItemExample { 147 @State numbers: String[] = ['0', '1', '2'] 148 149 build() { 150 Column({ space: 5 }) { 151 Grid() { 152 ForEach(this.numbers, (day: string) => { 153 ForEach(this.numbers, (day: string) => { 154 GridItem({style:GridItemStyle.NONE}) { 155 Text(day) 156 .fontSize(16) 157 .width('100%') 158 .height('100%') 159 .textAlign(TextAlign.Center) 160 .focusable(true) 161 } 162 .backgroundColor(0xF9CF93) 163 }, (day: string) => day) 164 }, (day: string) => day) 165 } 166 .columnsTemplate('1fr 1fr 1fr') 167 .rowsTemplate('1fr 1fr') 168 .columnsGap(4) 169 .rowsGap(4) 170 .width('60%') 171 .backgroundColor(0xFAEEE0) 172 .height(150) 173 .padding('4vp') 174 175 Grid() { 176 ForEach(this.numbers, (day: string) => { 177 ForEach(this.numbers, (day: string) => { 178 GridItem({style:GridItemStyle.PLAIN}) { 179 Text(day) 180 .fontSize(16) 181 .width('100%') 182 .height('100%') 183 .textAlign(TextAlign.Center) 184 .focusable(true) 185 } 186 .backgroundColor(0xF9CF93) 187 }, (day: string) => day) 188 }, (day: string) => day) 189 } 190 .columnsTemplate('1fr 1fr 1fr') 191 .rowsTemplate('1fr 1fr') 192 .columnsGap(4) 193 .rowsGap(4) 194 .width('60%') 195 .backgroundColor(0xFAEEE0) 196 .height(150) 197 .padding('4vp') 198 }.width('100%').margin({ top: 5 }) 199 } 200} 201``` 202 203 204
