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