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