1# GridItem 2 3网格容器中单项内容容器。 4 5> **说明：** 6> 7> * 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> * 仅支持作为[Grid](ts-container-grid.md)组件的子组件使用。 9> * 当GridItem配合LazyForEach使用时，GridItem子组件在GridItem创建时创建。配合if/else、ForEach使用时，或父组件为Grid时，GridItem子组件在GridItem布局时创建。 10 11 12## 子组件 13 14可以包含单个子组件。 15 16## 接口 17 18GridItem(value?: GridItemOptions) 19 20**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 21 22**系统能力：** SystemCapability.ArkUI.ArkUI.Full 23 24**参数：** 25 26| 参数名 | 类型 | 必填 | 说明 | 27| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 28| value<sup>11+</sup> | [GridItemOptions](#griditemoptions11对象说明) | 否 | 为GridItem提供可选参数, 该对象内含有[GridItemStyle](#griditemstyle11枚举说明)枚举类型的style参数。 | 29 30## 属性 31 32### rowStart 33 34rowStart(value: number) 35 36设置当前元素起始行号。 37 38**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 39 40**系统能力：** SystemCapability.ArkUI.ArkUI.Full 41 42**参数：** 43 44| 参数名 | 类型 | 必填 | 说明 | 45| ------ | ------ | ---- | ------------------ | 46| value | number | 是 | 当前元素起始行号。<br/>需要指定GridItem起始行列号和所占行列数的场景推荐使用[Grid的layoutOptions参数](ts-container-grid.md#gridlayoutoptions10)，详细可参考[Grid的示例1](ts-container-grid.md#示例1固定行列grid)和[Grid的示例3](ts-container-grid.md#示例3可滚动grid设置跨行跨列节点)。 | 47 48### rowEnd 49 50rowEnd(value: number) 51 52设置当前元素终点行号。 53 54**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 55 56**系统能力：** SystemCapability.ArkUI.ArkUI.Full 57 58**参数：** 59 60| 参数名 | 类型 | 必填 | 说明 | 61| ------ | ------ | ---- | ------------------ | 62| value | number | 是 | 当前元素终点行号。<br/>需要指定GridItem起始行列号和所占行列数的场景推荐使用[Grid的layoutOptions参数](ts-container-grid.md#gridlayoutoptions10)，详细可参考[Grid的示例1](ts-container-grid.md#示例1固定行列grid)和[Grid的示例3](ts-container-grid.md#示例3可滚动grid设置跨行跨列节点)。 | 63 64### columnStart 65 66columnStart(value: number) 67 68设置当前元素起始列号。 69 70**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 71 72**系统能力：** SystemCapability.ArkUI.ArkUI.Full 73 74**参数：** 75 76| 参数名 | 类型 | 必填 | 说明 | 77| ------ | ------ | ---- | ------------------ | 78| value | number | 是 | 当前元素起始列号。<br/>需要指定GridItem起始行列号和所占行列数的场景推荐使用[Grid的layoutOptions参数](ts-container-grid.md#gridlayoutoptions10)，详细可参考[Grid的示例1](ts-container-grid.md#示例1固定行列grid)和[Grid的示例3](ts-container-grid.md#示例3可滚动grid设置跨行跨列节点)。 | 79 80### columnEnd 81 82columnEnd(value: number) 83 84设置当前元素终点列号。 85 86**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 87 88**系统能力：** SystemCapability.ArkUI.ArkUI.Full 89 90**参数：** 91 92| 参数名 | 类型 | 必填 | 说明 | 93| ------ | ------ | ---- | ------------------ | 94| value | number | 是 | 当前元素终点列号。<br/>需要指定GridItem起始行列号和所占行列数的场景推荐使用[Grid的layoutOptions参数](ts-container-grid.md#gridlayoutoptions10)，详细可参考[Grid的示例1](ts-container-grid.md#示例1固定行列grid)和[Grid的示例3](ts-container-grid.md#示例3可滚动grid设置跨行跨列节点)。 | 95 96> **说明：** 97> 98> 需要指定GridItem起始行列号和所占行列数的场景推荐使用[Grid的layoutOptions参数](ts-container-grid.md#gridlayoutoptions10)，详细可参考[Grid的示例1](ts-container-grid.md#示例1固定行列grid)和[Grid的示例3](ts-container-grid.md#示例3可滚动grid设置跨行跨列节点)。 99> 100> 起始行号、终点行号、起始列号、终点列号生效规则如下： 101> 102> rowStart/rowEnd合理取值范围为0\~总行数-1，columnStart/columnEnd合理取值范围为0\~总列数-1。 103> 104> 如果设置了rowStart/rowEnd/columnStart/columnEnd，GridItem会占据指定的行数(rowEnd-rowStart+1)或列数(columnEnd-columnStart+1)。 105> 106> 只有在设置columnTemplate和rowTemplate的Grid中，设置合理的rowStart/rowEnd/columnStart/columnEnd四个属性的GridItem才能按照指定的行列号布局。 107> 108> 在设置columnTemplate和rowTemplate的Grid中，单独设置行号rowStart/rowEnd或列号columnStart/columnEnd的GridItem会按照一行一列进行布局。 109> 110> 在只设置columnTemplate的Grid中设置列号columnStart/columnEnd的GridItem按照列数布局。在该区域位置存在GridItem布局，则直接换行进行放置。 111> 112> 在只设置rowTemplate的Grid中设置行号rowStart/rowEnd的GridItem按照行数布局。在该区域位置存在GridItem布局，则直接换列进行放置。 113> 114> 在只设置columnTemplate的Grid中，在GridItem上设置了不合理的值，GridItem按照一行一列进行布局。 115> 116> columnTemplate和rowTemplate都不设置的Grid中GridItem的行列号属性无效。 117 118### forceRebuild<sup>(deprecated)</sup> 119 120forceRebuild(value: boolean) 121 122设置在触发组件build时是否重新创建此节点。GridItem会根据自身属性和子组件变化自行决定是否需要重新创建，无需设置。 123 124从API version9开始废弃。 125 126**系统能力：** SystemCapability.ArkUI.ArkUI.Full 127 128**参数：** 129 130| 参数名 | 类型 | 必填 | 说明 | 131| ------ | ------- | ---- | ------------------------------------------------------- | 132| value | boolean | 是 | 在触发组件build时是否重新创建此节点。<br/>默认值：false | 133 134### selectable<sup>8+</sup> 135 136selectable(value: boolean) 137 138设置当前GridItem元素是否可以被鼠标框选。外层Grid容器的鼠标框选开启时，GridItem的框选才生效。 139 140该属性需要在设置[选中态样式](./ts-universal-attributes-polymorphic-style.md#statestyles接口说明)前使用才能生效选中态样式。 141 142**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 143 144**系统能力：** SystemCapability.ArkUI.ArkUI.Full 145 146**参数：** 147 148| 参数名 | 类型 | 必填 | 说明 | 149| ------ | ------- | ---- | ----------------------------------------------------- | 150| value | boolean | 是 | 当前GridItem元素是否可以被鼠标框选。<br/>默认值：true | 151 152### selected<sup>10+</sup> 153 154selected(value: boolean) 155 156设置当前GridItem选中状态。该属性支持[$$](../../../quick-start/arkts-two-way-sync.md)双向绑定变量。 157 158该属性需要在设置[选中态样式](./ts-universal-attributes-polymorphic-style.md#statestyles接口说明)前使用才能生效选中态样式。 159 160**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 161 162**系统能力：** SystemCapability.ArkUI.ArkUI.Full 163 164**参数：** 165 166| 参数名 | 类型 | 必填 | 说明 | 167| ------ | ------- | ---- | ---------------------------------------- | 168| value | boolean | 是 | 当前GridItem选中状态。<br/>默认值：false | 169 170## GridItemOptions<sup>11+</sup>对象说明 171 172**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 173 174**系统能力：** SystemCapability.ArkUI.ArkUI.Full 175 176| 名称 | 类型 | 必填 | 说明 | 177| ----- | -------------------- | ---- | ---------------------------- | 178| style | [GridItemStyle](#griditemstyle11枚举说明) | 否 | 设置GridItem样式。<br/>默认值: GridItemStyle.NONE<br/>设置为GridItemStyle.NONE时无样式。<br/>设置为GridItemStyle.PLAIN时，显示Hover、Press态样式。 | 179 180## GridItemStyle<sup>11+</sup>枚举说明 181 182**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 183 184**系统能力：** SystemCapability.ArkUI.ArkUI.Full 185 186| 名称 |值| 说明 | 187| ----- |----| ------------------------ | 188| NONE | 0 | 无样式。 | 189| PLAIN | 1 | 显示Hover、Press态样式。 | 190 191> **说明：** 192> 193> GridItem焦点态样式设置：Grid组件需要设置4vp规格以上的内边距，用于显示GridItem的焦点框。 194 195## 事件 196 197### onSelect<sup>8+</sup> 198 199onSelect(event: (isSelected: boolean) => void) 200 201GridItem元素被鼠标框选的状态改变时触发回调。 202 203**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 204 205**系统能力：** SystemCapability.ArkUI.ArkUI.Full 206 207**参数：** 208 209| 参数名 | 类型 | 必填 | 说明 | 210| ---------- | ------- | ---- | ------------------------------------------------------------ | 211| isSelected | boolean | 是 | 进入鼠标框选范围即被选中返回true， 移出鼠标框选范围即未被选中返回false。 | 212 213## 示例 214 215### 示例1（GridItem设置自身位置） 216GridItem通过设置合理的ColumnStart、ColumnEnd、RowStart、RowEnd属性来设置自身位置。需要指定GridItem起始行列号和所占行列数的场景推荐使用[Grid的layoutOptions参数](ts-container-grid.md#gridlayoutoptions10)，详细可参考[Grid的示例1](ts-container-grid.md#示例1固定行列grid)和[Grid的示例3](ts-container-grid.md#示例3可滚动grid设置跨行跨列节点)。 217 218```ts 219// xxx.ets 220@Entry 221@Component 222struct GridItemExample { 223 @State numbers: string[] = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15"] 224 225 build() { 226 Column() { 227 Grid() { 228 GridItem() { 229 Text('4') 230 .fontSize(16) 231 .backgroundColor(0xFAEEE0) 232 .width('100%') 233 .height('100%') 234 .textAlign(TextAlign.Center) 235 }.rowStart(1).rowEnd(2).columnStart(1).columnEnd(2) // 同时设置合理的行列号 236 237 ForEach(this.numbers, (item: string) => { 238 GridItem() { 239 Text(item) 240 .fontSize(16) 241 .backgroundColor(0xF9CF93) 242 .width('100%') 243 .height('100%') 244 .textAlign(TextAlign.Center) 245 } 246 }, (item: string) => item) 247 248 GridItem() { 249 Text('5') 250 .fontSize(16) 251 .backgroundColor(0xDBD0C0) 252 .width('100%') 253 .height('100%') 254 .textAlign(TextAlign.Center) 255 }.columnStart(1).columnEnd(4) // 只设置列号，不会从第1列开始布局 256 } 257 .columnsTemplate('1fr 1fr 1fr 1fr 1fr') 258 .rowsTemplate('1fr 1fr 1fr 1fr 1fr') 259 .width('90%').height(300) 260 }.width('100%').margin({ top: 5 }) 261 } 262} 263``` 264 265 266 267### 示例2（设置GridItem样式） 268 269使用GridItemOptions设置GridItem样式。 270 271```ts 272// xxx.ets 273@Entry 274@Component 275struct GridItemExample { 276 @State numbers: String[] = ['0', '1', '2'] 277 278 build() { 279 Column({ space: 5 }) { 280 Grid() { 281 ForEach(this.numbers, (day: string) => { 282 ForEach(this.numbers, (day: string) => { 283 GridItem({style:GridItemStyle.NONE}) { 284 Text(day) 285 .fontSize(16) 286 .width('100%') 287 .height('100%') 288 .textAlign(TextAlign.Center) 289 .focusable(true) 290 } 291 .backgroundColor(0xF9CF93) 292 }, (day: string) => day) 293 }, (day: string) => day) 294 } 295 .columnsTemplate('1fr 1fr 1fr') 296 .rowsTemplate('1fr 1fr') 297 .columnsGap(4) 298 .rowsGap(4) 299 .width('60%') 300 .backgroundColor(0xFAEEE0) 301 .height(150) 302 .padding('4vp') 303 304 Grid() { 305 ForEach(this.numbers, (day: string) => { 306 ForEach(this.numbers, (day: string) => { 307 GridItem({style:GridItemStyle.PLAIN}) { 308 Text(day) 309 .fontSize(16) 310 .width('100%') 311 .height('100%') 312 .textAlign(TextAlign.Center) 313 .focusable(true) 314 } 315 .backgroundColor(0xF9CF93) 316 }, (day: string) => day) 317 }, (day: string) => day) 318 } 319 .columnsTemplate('1fr 1fr 1fr') 320 .rowsTemplate('1fr 1fr') 321 .columnsGap(4) 322 .rowsGap(4) 323 .width('60%') 324 .backgroundColor(0xFAEEE0) 325 .height(150) 326 .padding('4vp') 327 }.width('100%').margin({ top: 5 }) 328 } 329} 330``` 331 332 333
