1# Grid 2 3网格容器，由“行”和“列”分割的单元格所组成，通过指定“项目”所在的单元格做出各种各样的布局。 4 5> **说明：** 6> 7> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 子组件 11 12仅支持[GridItem](ts-container-griditem.md)子组件，支持渲染控制类型（[if/else](../../../quick-start/arkts-rendering-control-ifelse.md)、[ForEach](../../../quick-start/arkts-rendering-control-foreach.md)、[LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md)和[Repeat](../../../quick-start/arkts-new-rendering-control-repeat.md)）。 13 14> **说明：** 15> 16> Grid子组件的索引值计算规则： 17> 18> 按子组件的顺序依次递增。 19> 20> if/else语句中，只有条件成立分支内的子组件会参与索引值计算，条件不成立分支内的子组件不计算索引值。 21> 22> ForEach/LazyForEach和Repeat语句中，会计算展开所有子节点索引值。 23> 24> [if/else](../../../quick-start/arkts-rendering-control-ifelse.md)、[ForEach](../../../quick-start/arkts-rendering-control-foreach.md)、[LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md)和[Repeat](../../../quick-start/arkts-new-rendering-control-repeat.md)发生变化以后，会更新子节点索引值。 25> 26> Grid子组件的visibility属性设置为Hidden或None时依然会计算索引值。 27> 28> Grid子组件的visibility属性设置为None时不显示，但依然会占用子组件对应的网格。 29> 30> Grid子组件设置position属性，会占用子组件对应的网格，子组件将显示在相对Grid左上角偏移position的位置。该子组件不会随其对应网格滚动，在对应网格滑出Grid显示范围外后不显示。 31> 32> 当Grid子组件之间留有空隙时，会根据当前的展示区域尽可能填补空隙，因此GridItem可能会随着网格滚动而改变相对位置。 33 34## 接口 35 36Grid(scroller?: Scroller, layoutOptions?: GridLayoutOptions) 37 38**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 39 40**系统能力：** SystemCapability.ArkUI.ArkUI.Full 41 42**参数：** 43 44| 参数名 | 类型 | 必填 | 说明 | 45| -------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 46| scroller | [Scroller](ts-container-scroll.md#scroller) | 否 | 可滚动组件的控制器。用于与可滚动组件进行绑定。<br/>**说明：** <br/>不允许和其他滚动类组件，如：[List](ts-container-list.md)、[Grid](ts-container-grid.md)、[Scroll](ts-container-scroll.md)等绑定同一个滚动控制对象。 | 47| layoutOptions<sup>10+</sup> | [GridLayoutOptions](#gridlayoutoptions10对象说明) | 否 | Grid布局选项。 | 48 49## GridLayoutOptions<sup>10+</sup>对象说明 50 51**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 52 53**系统能力：** SystemCapability.ArkUI.ArkUI.Full 54 55布局选项。其中,irregularIndexes和onGetIrregularSizeByIndex可对仅设置rowsTemplate或columnsTemplate的Grid使用，可以指定一个index数组，并为其中的index对应的GridItem设置其占据的行数与列数，使用方法参见示例3；onGetRectByIndex可对同时设置rowsTemplate和columnsTemplate的Grid使用，为指定的index对应的GridItem设置位置和大小，使用方法参见示例1。 56 57| 名称 | 类型 | 必填 | 说明 | 58| ----- | ------- | ---- | --------------------- | 59| regularSize | [number, number] | 是 | 大小规则的GridItem在Grid中占的行数和列数，只支持占1行1列即[1, 1]。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 60| irregularIndexes | number[] | 否 | 指定的GridItem索引在Grid中的大小是不规则的。当不设置onGetIrregularSizeByIndex时，irregularIndexes中GridItem的默认大小为垂直滚动Grid的一整行或水平滚动Grid的一整列。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 61| onGetIrregularSizeByIndex | (index: number) => [number, number] | 否 | 配合irregularIndexes使用，设置不规则GridItem占用的行数和列数。开发者可为irregularIndexes中指明的index对应的GridItem设置占用的行数和列数。在API version 12之前，垂直滚动Grid不支持GridItem占多行，水平滚动Grid不支持GridItem占多列。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 62| onGetRectByIndex<sup>11+</sup> | (index: number) => [number, number,number,number] | 否 | 设置指定索引index对应的GridItem的位置及大小[rowStart,columnStart,rowSpan,columnSpan]。 <br/>其中rowStart为行起始位置，columnStart为列起始位置，无单位。 <br/>rowSpan为GridItem占用的行数，columnSpan为GridItem占用的列数，无单位。 <br/>rowStart和columnStart取大于等于0的自然数，若取负数时，rowStart和columnStart默认为0。 <br/>rowSpan和columnSpan取大于等于1的自然数，若取小数则向下取整，若小于1则按1计算。<br/>**说明：** <br/>第一种情况：某个GridItem发现给它指定的起始位置被占据了，则从起始位置[0,0]开始按顺序从左到右，从上到下寻找起始的放置位置。<br/>第二种情况：如果起始位置没有被占据，但其他位置被占据了，无法显示全部的GridItem大小，则只会布局一部分。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 63 64## 属性 65 66除支持[通用属性](ts-universal-attributes-size.md)和[滚动组件通用属性](ts-container-scrollable-common.md#属性)外，还支持以下属性： 67 68### columnsTemplate 69 70columnsTemplate(value: string) 71 72设置当前网格布局列的数量、固定列宽或最小列宽值，不设置时默认1列。 73 74例如, '1fr 1fr 2fr' 是将父组件分3列，将父组件允许的宽分为4等份，第一列占1份，第二列占1份，第三列占2份。 75 76columnsTemplate('repeat(auto-fit, track-size)')是设置最小列宽值为track-size，自动计算列数和实际列宽。 77 78columnsTemplate('repeat(auto-fill, track-size)')是设置固定列宽值为track-size，自动计算列数。 79 80columnsTemplate('repeat(auto-stretch, track-size)')是设置固定列宽值为track-size，使用columnsGap为最小列间距，自动计算列数和实际列间距。 81 82其中repeat、auto-fit、auto-fill、auto-stretch为关键字。track-size为列宽，支持的单位包括px、vp、%或有效数字，默认单位为vp，track-size至少包括一个有效列宽。<br/> 83auto-stretch模式只支持track-size为一个有效列宽值，并且track-size只支持px、vp和有效数字，不支持%。 84 85使用效果可以参考示[示例8](#示例8)。 86 87设置为'0fr'时，该列的列宽为0，不显示GridItem。设置为其他非法值时，GridItem显示为固定1列。 88 89**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 90 91**系统能力：** SystemCapability.ArkUI.ArkUI.Full 92 93**参数：** 94 95| 参数名 | 类型 | 必填 | 说明 | 96| ------ | ------ | ---- | ---------------------------------- | 97| value | string | 是 | 当前网格布局列的数量或最小列宽值。 | 98 99### rowsTemplate 100 101rowsTemplate(value: string) 102 103设置当前网格布局行的数量、固定行高或最小行高值，不设置时默认1行。 104 105例如, '1fr 1fr 2fr'是将父组件分3行，将父组件允许的高分为4等份，第一行占1份，第二行占一份，第三行占2份。 106 107rowsTemplate('repeat(auto-fit, track-size)')是设置最小行高值为track-size，自动计算行数和实际行高。 108 109rowsTemplate('repeat(auto-fill, track-size)')是设置固定行高值为track-size，自动计算行数。 110 111rowsTemplate('repeat(auto-stretch, track-size)')是设置固定行高值为track-size，使用rowsGap为最小行间距，自动计算行数和实际行间距。 112 113其中repeat、auto-fit、auto-fill、auto-stretch为关键字。track-size为行高，支持的单位包括px、vp、%或有效数字，默认单位为vp，track-size至少包括一个有效行高。<br/> 114auto-stretch模式只支持track-size为一个有效行高值，并且track-size只支持px、vp和有效数字，不支持%。 115 116设置为'0fr'，则这一行的行宽为0，这一行GridItem不显示。设置为其他非法值，按固定1行处理。 117 118**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 119 120**系统能力：** SystemCapability.ArkUI.ArkUI.Full 121 122**参数：** 123 124| 参数名 | 类型 | 必填 | 说明 | 125| ------ | ------ | ---- | ---------------------------------- | 126| value | string | 是 | 当前网格布局行的数量或最小行高值。 | 127 128> **说明：** 129> 130> Grid组件根据rowsTemplate、columnsTemplate属性的设置情况，可分为以下三种布局模式： 131> 132> 1、rowsTemplate、columnsTemplate同时设置： 133> 134> - Grid只展示固定行列数的元素，其余元素不展示，且Grid不可滚动。 135> - 此模式下以下属性不生效：layoutDirection、maxCount、minCount、cellLength。 136> - Grid的宽高没有设置时，默认适应父组件尺寸。 137> - Grid网格列大小按照Grid自身内容区域大小减去所有行列Gap后按各个行列所占比重分配。 138> - GridItem默认填满网格大小。 139> 140> 2、rowsTemplate、columnsTemplate仅设置其中的一个： 141> 142> - 元素按照设置的方向进行排布，超出Grid显示区域后，Grid可通过滚动的方式展示。 143> - 如果设置了columnsTemplate，Grid滚动方向为垂直方向，主轴方向为垂直方向，交叉轴方向为水平方向。 144> - 如果设置了rowsTemplate，Grid滚动方向为水平方向，主轴方向为水平方向，交叉轴方向为垂直方向。 145> - 此模式下以下属性不生效：layoutDirection、maxCount、minCount、cellLength。 146> - 网格交叉轴方向尺寸根据Grid自身内容区域交叉轴尺寸减去交叉轴方向所有Gap后按所占比重分配。 147> - 网格主轴方向尺寸取当前网格交叉轴方向所有GridItem高度最大值。 148> 149> 3、rowsTemplate、columnsTemplate都不设置： 150> 151> - 元素在layoutDirection方向上排布，列数由Grid的宽度、首个元素的宽度、minCount、maxCount、columnsGap共同决定。 152> - 行数由Grid高度、首个元素高度、cellLength、rowsGap共同决定。超出行列容纳范围的元素不显示，也不能通过滚动进行展示。 153> - 此模式下仅生效以下属性：layoutDirection、maxCount、minCount、cellLength、editMode、columnsGap、rowsGap。 154> - 当前layoutDirection设置为Row时，先从左到右排列，排满一行再排下一行。剩余高度不足时不再布局，整体内容顶部居中。 155> - 当前layoutDirection设置为Column时，先从上到下排列，排满一列再排下一列，剩余宽度不足时不再布局。整体内容顶部居中。 156> - 当前Grid下面没有GridItem时，Grid的宽高为0。 157> 158 159### columnsGap 160 161columnsGap(value: Length) 162 163设置列与列的间距。设置为小于0的值时，按默认值显示。 164 165**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 166 167**系统能力：** SystemCapability.ArkUI.ArkUI.Full 168 169**参数：** 170 171| 参数名 | 类型 | 必填 | 说明 | 172| ------ | ---------------------------- | ---- | ---------------------------- | 173| value | [Length](ts-types.md#length) | 是 | 列与列的间距。<br/>默认值：0 | 174 175### rowsGap 176 177rowsGap(value: Length) 178 179设置行与行的间距。设置为小于0的值时，按默认值显示。 180 181**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 182 183**系统能力：** SystemCapability.ArkUI.ArkUI.Full 184 185**参数：** 186 187| 参数名 | 类型 | 必填 | 说明 | 188| ------ | ---------------------------- | ---- | ---------------------------- | 189| value | [Length](ts-types.md#length) | 是 | 行与行的间距。<br/>默认值：0 | 190 191### scrollBar 192 193scrollBar(value: BarState) 194 195设置滚动条状态。 196 197**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 198 199**系统能力：** SystemCapability.ArkUI.ArkUI.Full 200 201**参数：** 202 203| 参数名 | 类型 | 必填 | 说明 | 204| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 205| value | [BarState](ts-appendix-enums.md#barstate) | 是 | 滚动条状态。<br/>默认值：BarState.Auto<br/>**说明：** <br/>API version 9及以下版本默认值为BarState.Off，API version 10及以上版本的默认值为BarState.Auto。 | 206 207### scrollBarColor 208 209scrollBarColor(value: Color | number | string) 210 211设置滚动条的颜色。 212 213**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 214 215**系统能力：** SystemCapability.ArkUI.ArkUI.Full 216 217**参数：** 218 219| 参数名 | 类型 | 必填 | 说明 | 220| ------ | ------------------------------------------------------------ | ---- | -------------- | 221| value | [Color](ts-appendix-enums.md#color) \| number \| string | 是 | 滚动条的颜色。<br/>默认值：'\#182431'（40%不透明度） | 222 223### scrollBarWidth 224 225scrollBarWidth(value: number | string) 226 227设置滚动条的宽度，不支持百分比设置。宽度设置后，滚动条正常状态和按压状态宽度均为滚动条的宽度值。如果滚动条的宽度超过Grid组件主轴方向的高度，则滚动条的宽度会变为默认值。 228 229**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 230 231**系统能力：** SystemCapability.ArkUI.ArkUI.Full 232 233**参数：** 234 235| 参数名 | 类型 | 必填 | 说明 | 236| ------ | -------------------------- | ---- | ----------------------------------------- | 237| value | number \| string | 是 | 滚动条的宽度。<br/>默认值：4<br/>单位：vp | 238 239### cachedCount 240 241cachedCount(value: number) 242 243设置预加载的GridItem的数量，只在[LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md)和开启了virtualScroll开关的[Repeat](../../../quick-start/arkts-new-rendering-control-repeat.md)中生效。设置为小于0的值时，按默认值显示。<!--Del-->具体使用可参考[减少应用白块说明](../../../performance/arkts-performance-improvement-recommendation.md#减少应用滑动白块)。<!--DelEnd--> 244 245设置缓存后会在Grid显示区域上下各缓存cachedCount*列数个GridItem。 246 247[LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md)和开启了virtualScroll开关的[Repeat](../../../quick-start/arkts-new-rendering-control-repeat.md)超出显示和缓存范围的GridItem会被释放。 248 249**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 250 251**系统能力：** SystemCapability.ArkUI.ArkUI.Full 252 253**参数：** 254 255| 参数名 | 类型 | 必填 | 说明 | 256| ------ | ------ | ---- | -------------------------------------- | 257| value | number | 是 | 预加载的GridItem的数量。<br/>默认值：1 | 258 259### editMode<sup>8+</sup> 260 261editMode(value: boolean) 262 263设置Grid是否进入编辑模式，进入编辑模式可以拖拽Grid组件内部[GridItem](ts-container-griditem.md)。 264 265**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 266 267**系统能力：** SystemCapability.ArkUI.ArkUI.Full 268 269**参数：** 270 271| 参数名 | 类型 | 必填 | 说明 | 272| ------ | ------ | ---- | ---------------------------------------- | 273| value | boolean | 是 | Grid是否进入编辑模式。<br/>默认值：false | 274 275### layoutDirection<sup>8+</sup> 276 277layoutDirection(value: GridDirection) 278 279设置布局的主轴方向。 280 281**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 282 283**系统能力：** SystemCapability.ArkUI.ArkUI.Full 284 285**参数：** 286 287| 参数名 | 类型 | 必填 | 说明 | 288| ------ | ---------------------------------------- | ---- | ---------------------------------------------- | 289| value | [GridDirection](#griddirection8枚举说明) | 是 | 布局的主轴方向。<br/>默认值：GridDirection.Row | 290 291### maxCount<sup>8+</sup> 292 293maxCount(value: number) 294 295设置可显示的最大行数或列数。设置为小于1的值时，按默认值显示。 296 297当layoutDirection是Row/RowReverse时，表示可显示的最大列数。 298 299当layoutDirection是Column/ColumnReverse时，表示可显示的最大行数。 300 301当maxCount小于minCount时，maxCount和minCount都按默认值处理。 302 303**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 304 305**系统能力：** SystemCapability.ArkUI.ArkUI.Full 306 307**参数：** 308 309| 参数名 | 类型 | 必填 | 说明 | 310| ------ | ------ | ---- | --------------------------------------------- | 311| value | number | 是 | 可显示的最大行数或列数。<br/>默认值：Infinity | 312 313### minCount<sup>8+</sup> 314 315minCount(value: number) 316 317设置可显示的最小行数或列数。设置为小于1的值时，按默认值显示。 318 319当layoutDirection是Row/RowReverse时，表示可显示的最小列数。 320 321当layoutDirection是Column/ColumnReverse时，表示可显示的最小行数。 322 323**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 324 325**系统能力：** SystemCapability.ArkUI.ArkUI.Full 326 327**参数：** 328 329| 参数名 | 类型 | 必填 | 说明 | 330| ------ | ------ | ---- | -------------------------------------- | 331| value | number | 是 | 可显示的最小行数或列数。<br/>默认值：1 | 332 333### cellLength<sup>8+</sup> 334 335cellLength(value: number) 336 337设置一行的高度或者一列的宽度。 338 339当layoutDirection是Row/RowReverse时，表示一行的高度。 340 341当layoutDirection是Column/ColumnReverse时，表示一列的宽度。 342 343**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 344 345**系统能力：** SystemCapability.ArkUI.ArkUI.Full 346 347**参数：** 348 349| 参数名 | 类型 | 必填 | 说明 | 350| ------ | ------ | ---- | ------------------------------------------------------- | 351| value | number | 是 | 一行的高度或者一列的宽度。<br/>默认值：第一个元素的大小 <br/>单位：vp| 352 353### multiSelectable<sup>8+</sup> 354 355multiSelectable(value: boolean) 356 357设置是否开启鼠标框选。开启框选后，可以配合Griditem的selected属性和onSelect事件获取GridItem的选中状态，还可以设置[选中态样式](./ts-universal-attributes-polymorphic-style.md)（无默认选中样式）。 358 359**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 360 361**系统能力：** SystemCapability.ArkUI.ArkUI.Full 362 363**参数：** 364 365| 参数名 | 类型 | 必填 | 说明 | 366| ------ | ------- | ---- | ------------------------------------------------------------ | 367| value | boolean | 是 | 是否开启鼠标框选。<br/>默认值：false<br/>false：关闭框选。true：开启框选。 | 368 369### supportAnimation<sup>8+</sup> 370 371supportAnimation(value: boolean) 372 373设置是否支持动画。当前支持GridItem拖拽动画。仅在滚动模式下（只设置rowsTemplate、columnsTemplate其中一个）支持动画。<br/>仅在大小规则的Grid中支持拖拽动画，跨行或跨列场景不支持。 374 375**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 376 377**系统能力：** SystemCapability.ArkUI.ArkUI.Full 378 379**参数：** 380 381| 参数名 | 类型 | 必填 | 说明 | 382| ------ | ------- | ---- | -------------------------------- | 383| value | boolean | 是 | 是否支持动画。<br/>默认值：false | 384 385### edgeEffect<sup>10+</sup> 386 387edgeEffect(value: EdgeEffect, options?: EdgeEffectOptions) 388 389设置边缘滑动效果。 390 391**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 392 393**系统能力：** SystemCapability.ArkUI.ArkUI.Full 394 395**参数：** 396 397| 参数名 | 类型 | 必填 | 说明 | 398| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 399| value | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | 是 | Grid组件的边缘滑动效果，支持弹簧效果和阴影效果。<br/>默认值：EdgeEffect.None | 400| options<sup>11+</sup> | [EdgeEffectOptions](ts-container-scrollable-common.md#edgeeffectoptions11对象说明) | 否 | 组件内容大小小于组件自身时，是否开启滑动效果。设置为{ alwaysEnabled: true }会开启滑动效果，{ alwaysEnabled: false }不开启。<br/>默认值：{ alwaysEnabled: false } | 401 402### enableScrollInteraction<sup>10+</sup> 403 404enableScrollInteraction(value: boolean) 405 406设置是否支持滚动手势，当设置为false时，无法通过手指或者鼠标滚动，但不影响控制器的滚动接口。 407 408**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 409 410**系统能力：** SystemCapability.ArkUI.ArkUI.Full 411 412**参数：** 413 414| 参数名 | 类型 | 必填 | 说明 | 415| ------ | ------- | ---- | ----------------------------------- | 416| value | boolean | 是 | 是否支持滚动手势。<br/>默认值：true | 417 418### nestedScroll<sup>10+</sup> 419 420nestedScroll(value: NestedScrollOptions) 421 422设置嵌套滚动选项。设置向前向后两个方向上的嵌套滚动模式，实现与父组件的滚动联动。 423 424**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 425 426**系统能力：** SystemCapability.ArkUI.ArkUI.Full 427 428**参数：** 429 430| 参数名 | 类型 | 必填 | 说明 | 431| ------ | ------------------------------------------------------------ | ---- | -------------- | 432| value | [NestedScrollOptions](ts-container-scrollable-common.md#nestedscrolloptions10对象说明) | 是 | 嵌套滚动选项。 | 433 434### friction<sup>10+</sup> 435 436friction(value: number | Resource) 437 438设置摩擦系数，手动划动滚动区域时生效，只对惯性滚动过程有影响，对惯性滚动过程中的链式效果有间接影响。设置为小于等于0的值时，按默认值处理 439 440**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 441 442**系统能力：** SystemCapability.ArkUI.ArkUI.Full 443 444**参数：** 445 446| 参数名 | 类型 | 必填 | 说明 | 447| ------ | ---------------------------------------------------- | ---- | ----------------------------------------------------------- | 448| value | number \| [Resource](ts-types.md#resource) | 是 | 摩擦系数。<br/>默认值：非可穿戴设备为0.6，可穿戴设备为0.9。<br/>从API version 11开始，非可穿戴设备默认值为0.7。<br/>从API version 12开始，非可穿戴设备默认值为0.75。 | 449 450### alignItems<sup>12+</sup> 451 452alignItems(alignment: Optional\<GridItemAlignment\>) 453 454设置Grid中GridItem的对齐方式， 使用方法可以参考[示例9](#示例9)。 455 456**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 457 458**系统能力：** SystemCapability.ArkUI.ArkUI.Full 459 460**参数：** 461 462| 参数名 | 类型 | 必填 | 说明 | 463| ---------- | ------ | ---- | ------------------------------- | 464| alignment | Optional\<[GridItemAlignment](#griditemalignment12枚举说明)\> | 是 | 设置Grid中GridItem的对齐方式。<br/>默认值：GridItemAlignment.DEFAULT | 465 466## GridItemAlignment<sup>12+</sup>枚举说明 467 468**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 469 470**系统能力：** SystemCapability.ArkUI.ArkUI.Full 471 472| 名称 | 值 | 说明 | 473| ------ |------| -------------------------------------- | 474| DEFAULT | 0 | 使用Grid的默认对齐方式。 | 475| STRETCH | 1 | 以一行中的最高的GridItem作为其他GridItem的高度。 | 476 477 478> **说明：** 479> 480> 1、只有可滚动的Grid中，设置STRETCH参数会生效，其他场景不生效。<br/> 481> 2、在Grid的一行中，如果每个GridItem都是大小规律的（只占一行一列），设置STRETCH参数会生效，存在跨行或跨列的GridItem的场景不生效。<br/> 482> 3、设置STRETCH后，只有不设置高度的GridItem才会以当前行中最高的GridItem作为自己的高度，设置过高度的GridItem高度不会变化。<br/> 483> 4、设置STRETCH后，Grid布局时会有额外的布局流程，可能会带来额外的性能开销。 484 485## GridDirection<sup>8+</sup>枚举说明 486 487**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 488 489**系统能力：** SystemCapability.ArkUI.ArkUI.Full 490 491| 名称 |值| 说明 | 492| ------ |------| -------------------------------------- | 493| Row | 0 | 主轴布局方向沿水平方向布局，即自左往右先填满一行，再去填下一行。 | 494| Column | 1 | 主轴布局方向沿垂直方向布局，即自上往下先填满一列，再去填下一列。 | 495| RowReverse | 2 | 主轴布局方向沿水平方向反向布局，即自右往左先填满一行，再去填下一行。 | 496| ColumnReverse | 3 | 主轴布局方向沿垂直方向反向布局，即自下往上先填满一列，再去填下一列。 | 497 498> **说明：** 499> 500> Grid组件[通用属性clip](ts-universal-attributes-sharp-clipping.md)的默认值为true。 501 502## 事件 503 504除支持[通用事件](ts-universal-events-click.md)和[滚动组件通用事件](ts-container-scrollable-common.md#事件)外，还支持以下事件： 505 506### onScrollIndex 507 508onScrollIndex(event: (first: number, last: number) => void) 509 510当前网格显示的起始位置/终止位置的item发生变化时触发。网格初始化时会触发一次。Grid显示区域上第一个子组件/最后一个组件的索引值有变化就会触发。 511 512**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 513 514**系统能力：** SystemCapability.ArkUI.ArkUI.Full 515 516**参数：** 517 518| 参数名 | 类型 | 必填 | 说明 | 519| ------------------ | ------ | ---- | -------------------------------- | 520| first | number | 是 | 当前显示的网格起始位置的索引值。 | 521| last<sup>10+</sup> | number | 是 | 当前显示的网格终止位置的索引值。 | 522 523### onItemDragStart<sup>8+</sup> 524 525onItemDragStart(event: (event: ItemDragInfo, itemIndex: number) => (() => any) \| void) 526 527开始拖拽网格元素时触发。返回void表示不能拖拽。 528 529手指长按GridItem时触发该事件。 530 531由于拖拽检测也需要长按，且事件处理机制优先触发子组件事件，GridItem上绑定LongPressGesture时无法触发拖拽。如有长按和拖拽同时使用的需求可以使用通用拖拽事件。 532 533**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 534 535**系统能力：** SystemCapability.ArkUI.ArkUI.Full 536 537**参数：** 538 539| 参数名 | 类型 | 必填 | 说明 | 540| --------- | ------------------------------------- | ---- | ---------------------- | 541| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo对象说明) | 是 | 拖拽点的信息。 | 542| itemIndex | number | 是 | 被拖拽网格元素索引值。 | 543 544### onItemDragEnter<sup>8+</sup> 545 546onItemDragEnter(event: (event: ItemDragInfo) => void) 547 548拖拽进入网格元素范围内时触发。 549 550**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 551 552**系统能力：** SystemCapability.ArkUI.ArkUI.Full 553 554**参数：** 555 556| 参数名 | 类型 | 必填 | 说明 | 557| ------ | ------------------------------------- | ---- | -------------- | 558| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo对象说明) | 是 | 拖拽点的信息。 | 559 560### onItemDragMove<sup>8+</sup> 561 562onItemDragMove(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number) => void) 563 564拖拽在网格元素范围内移动时触发。 565 566**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 567 568**系统能力：** SystemCapability.ArkUI.ArkUI.Full 569 570**参数：** 571 572| 参数名 | 类型 | 必填 | 说明 | 573| ----------- | ------------------------------------- | ---- | -------------- | 574| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo对象说明) | 是 | 拖拽点的信息。 | 575| itemIndex | number | 是 | 拖拽起始位置。 | 576| insertIndex | number | 是 | 拖拽插入位置。 | 577 578### onItemDragLeave<sup>8+</sup> 579 580onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void) 581 582拖拽离开网格元素时触发。 583 584**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 585 586**系统能力：** SystemCapability.ArkUI.ArkUI.Full 587 588**参数：** 589 590| 参数名 | 类型 | 必填 | 说明 | 591| --------- | ------------------------------------- | ---- | -------------------------- | 592| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo对象说明) | 是 | 拖拽点的信息。 | 593| itemIndex | number | 是 | 拖拽离开的网格元素索引值。 | 594 595### onItemDrop<sup>8+</sup> 596 597onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void) 598 599绑定该事件的网格元素可作为拖拽释放目标，当在网格元素内停止拖拽时触发。 600 601**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 602 603**系统能力：** SystemCapability.ArkUI.ArkUI.Full 604 605**参数：** 606 607| 参数名 | 类型 | 必填 | 说明 | 608| ----------- | ------------------------------------- | ---- | -------------- | 609| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo对象说明) | 是 | 拖拽点的信息。 | 610| itemIndex | number | 是 | 拖拽起始位置。 | 611| insertIndex | number | 是 | 拖拽插入位置。 | 612| isSuccess | boolean | 是 | 是否成功释放 | 613 614### onScrollBarUpdate<sup>10+</sup> 615 616onScrollBarUpdate(event: (index: number, offset: number) => ComputedBarAttribute) 617 618当前网格显示的起始位置item发生变化时触发，可通过该回调设置滚动条的位置及长度。 619 620**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 621 622**系统能力：** SystemCapability.ArkUI.ArkUI.Full 623 624**参数：** 625 626| 参数名 | 类型 | 必填 | 说明 | 627| ------ | ------ | ---- | ------------------------------------------------------------ | 628| index | number | 是 | 当前显示的网格起始位置的索引值。 | 629| offset | number | 是 | 当前显示的网格起始位置元素相对网格显示起始位置的偏移，单位vp。 | 630 631**返回值：** 632 633| 类型 | 说明 | 634| ----------------------------------------------------- | -------------------- | 635| [ComputedBarAttribute](#computedbarattribute10对象说明) | 滚动条的位置及长度。 | 636 637### onReachStart<sup>10+</sup> 638 639onReachStart(event: () => void) 640 641网格到达起始位置时触发。 642 643Grid初始化时会触发一次，Grid滚动到起始位置时触发一次。Grid边缘效果为弹簧效果时，划动经过起始位置时触发一次，回弹回起始位置时再触发一次。 644 645**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 646 647**系统能力：** SystemCapability.ArkUI.ArkUI.Full 648 649### onReachEnd<sup>10+</sup> 650 651onReachEnd(event: () => void) 652 653网格到达末尾位置时触发。 654 655Grid边缘效果为弹簧效果时，划动经过末尾位置时触发一次，回弹回末尾位置时再触发一次。 656 657**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 658 659**系统能力：** SystemCapability.ArkUI.ArkUI.Full 660 661### onScrollFrameBegin<sup>10+</sup> 662 663onScrollFrameBegin(event: (offset: number, state: ScrollState) => { offsetRemain: number }) 664 665网格开始滑动时触发，事件参数传入即将发生的滑动量，事件处理函数中可根据应用场景计算实际需要的滑动量并作为事件处理函数的返回值返回，网格将按照返回值的实际滑动量进行滑动。 666 667**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 668 669**系统能力：** SystemCapability.ArkUI.ArkUI.Full 670 671**参数：** 672 673| 参数名 | 类型 | 必填 | 说明 | 674| ------ | ------------------------------------------------------- | ---- | -------------------------- | 675| offset | number | 是 | 即将发生的滑动量，单位vp。 | 676| state | [ScrollState](ts-container-list.md#scrollstate枚举说明) | 是 | 当前滑动状态。 | 677 678**返回值：** 679 680| 类型 | 说明 | 681| ------------------------ | -------------------- | 682| { offsetRemain: number } | 实际滑动量，单位vp。 | 683 684### onScrollStart<sup>10+</sup> 685 686onScrollStart(event: () => void) 687 688网格滑动开始时触发。手指拖动网格或网格的滚动条触发的滑动开始时，会触发该事件。使用[Scroller](ts-container-scroll.md#scroller)滑动控制器触发的带动画的滑动，动画开始时会触发该事件。 689 690**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 691 692**系统能力：** SystemCapability.ArkUI.ArkUI.Full 693 694### onScrollStop<sup>10+</sup> 695 696onScrollStop(event: () => void) 697 698网格滑动停止时触发。手指拖动网格或网格的滚动条触发的滑动，手指离开屏幕并且滑动停止时会触发该事件。使用[Scroller](ts-container-scroll.md#scroller)滑动控制器触发的带动画的滑动，动画停止会触发该事件。 699 700**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 701 702**系统能力：** SystemCapability.ArkUI.ArkUI.Full 703 704### onScroll<sup>(deprecated)</sup> 705onScroll(event: (scrollOffset: number, scrollState: [ScrollState](ts-container-list.md#scrollstate枚举说明)) => void) 706 707网格滑动时触发。 708 709从API version 10开始使用。 710 711从API version 12开始废弃不再使用，建议使用[onDidScroll](ts-container-scrollable-common.md#ondidscroll12)替代。 712 713**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 714 715**系统能力：** SystemCapability.ArkUI.ArkUI.Full 716 717**参数：** 718 719| 参数名 | 类型 | 必填 | 说明 | 720| ------ | ------ | ------ | ------| 721| scrollOffset | number | 是 | 每帧滚动的偏移量，Grid的内容向上滚动时偏移量为正，向下滚动时偏移量为负。<br/>单位vp。 | 722| scrollState | [ScrollState](ts-container-list.md#scrollstate枚举说明) | 是 | 当前滑动状态。 | 723 724## ComputedBarAttribute<sup>10+</sup>对象说明 725 726**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 727 728**系统能力：** SystemCapability.ArkUI.ArkUI.Full 729 730| 名称 | 类型 | 只读 | 可选 | 说明 | 731| ----------- | ------------ | ---- | ---- | ---------- | 732| totalOffset | number | 否 | 否 | Grid内容相对显示区域的总偏移，单位px。 | 733| totalLength | number | 否 | 否 | Grid内容总长度，单位px。 | 734 735## 示例 736 737### 示例1 738 739固定行列的Grid，可以使用GridLayoutOptions中的onGetRectByIndex指定GridItem的位置和大小。 740 741```ts 742// xxx.ets 743@Entry 744@Component 745struct GridExample { 746 @State numbers1: String[] = ['0', '1', '2', '3', '4'] 747 @State numbers2: String[] = ['0', '1','2','3','4','5'] 748 749 layoutOptions3: GridLayoutOptions = { 750 regularSize: [1, 1], 751 onGetRectByIndex: (index: number) => { 752 if (index == 0) 753 return [0, 0, 1, 1] 754 else if(index==1) 755 return [0, 1, 2, 2] 756 else if(index==2) 757 return [0 ,3 ,3 ,3] 758 else if(index==3) 759 return [3, 0, 3, 3] 760 else if(index==4) 761 return [4, 3, 2, 2] 762 else 763 return [5, 5, 1, 1] 764 } 765 } 766 767 build() { 768 Column({ space: 5 }) { 769 Grid() { 770 ForEach(this.numbers1, (day: string) => { 771 ForEach(this.numbers1, (day: string) => { 772 GridItem() { 773 Text(day) 774 .fontSize(16) 775 .backgroundColor(0xF9CF93) 776 .width('100%') 777 .height('100%') 778 .textAlign(TextAlign.Center) 779 } 780 }, (day: string) => day) 781 }, (day: string) => day) 782 } 783 .columnsTemplate('1fr 1fr 1fr 1fr 1fr') 784 .rowsTemplate('1fr 1fr 1fr 1fr 1fr') 785 .columnsGap(10) 786 .rowsGap(10) 787 .width('90%') 788 .backgroundColor(0xFAEEE0) 789 .height(300) 790 791 Text('GridLayoutOptions的使用：onGetRectByIndex。').fontColor(0xCCCCCC).fontSize(9).width('90%') 792 793 Grid(undefined, this.layoutOptions3) { 794 ForEach(this.numbers2, (day: string) => { 795 GridItem() { 796 Text(day) 797 .fontSize(16) 798 .backgroundColor(0xF9CF93) 799 .width('100%') 800 .height("100%") 801 .textAlign(TextAlign.Center) 802 } 803 .height("100%") 804 .width('100%') 805 }, (day: string) => day) 806 } 807 .columnsTemplate('1fr 1fr 1fr 1fr 1fr 1fr') 808 .rowsTemplate('1fr 1fr 1fr 1fr 1fr 1fr') 809 .columnsGap(10) 810 .rowsGap(10) 811 .width('90%') 812 .backgroundColor(0xFAEEE0) 813 .height(300) 814 }.width('100%').margin({ top: 5 }) 815 } 816} 817``` 818 819 820 821### 示例2 822 823可滚动Grid，包括所有滚动属性和事件。 824 825```ts 826// xxx.ets 827@Entry 828@Component 829struct GridExample { 830 @State numbers: String[] = ['0', '1', '2', '3', '4'] 831 scroller: Scroller = new Scroller() 832 @State gridPosition: number = 0 //0代表滚动到grid顶部，1代表中间值，2代表滚动到grid底部。 833 834 build() { 835 Column({ space: 5 }) { 836 Text('scroll').fontColor(0xCCCCCC).fontSize(9).width('90%') 837 Grid(this.scroller) { 838 ForEach(this.numbers, (day: string) => { 839 ForEach(this.numbers, (day: string) => { 840 GridItem() { 841 Text(day) 842 .fontSize(16) 843 .backgroundColor(0xF9CF93) 844 .width('100%') 845 .height(80) 846 .textAlign(TextAlign.Center) 847 } 848 }, (day: string) => day) 849 }, (day: string) => day) 850 } 851 .columnsTemplate('1fr 1fr 1fr 1fr 1fr') 852 .columnsGap(10) 853 .rowsGap(10) 854 .friction(0.6) 855 .enableScrollInteraction(true) 856 .supportAnimation(false) 857 .multiSelectable(false) 858 .edgeEffect(EdgeEffect.Spring) 859 .scrollBar(BarState.On) 860 .scrollBarColor(Color.Grey) 861 .scrollBarWidth(4) 862 .width('90%') 863 .backgroundColor(0xFAEEE0) 864 .height(300) 865 .onScrollIndex((first: number, last: number) => { 866 console.info(first.toString()) 867 console.info(last.toString()) 868 }) 869 .onScrollBarUpdate((index: number, offset: number) => { 870 console.info("XXX" + 'Grid onScrollBarUpdate,index : ' + index.toString() + ",offset" + offset.toString()) 871 return { totalOffset: (index / 5) * (80 + 10) - offset, totalLength: 80 * 5 + 10 * 4 } 872 }) //只适用于当前示例代码数据源，如果数据源有变化，则需要修改该部分代码，或者删掉此属性 873 .onDidScroll((scrollOffset: number, scrollState: ScrollState) => { 874 console.info(scrollOffset.toString()) 875 console.info(scrollState.toString()) 876 }) 877 .onScrollStart(() => { 878 console.info("XXX" + "Grid onScrollStart") 879 }) 880 .onScrollStop(() => { 881 console.info("XXX" + "Grid onScrollStop") 882 }) 883 .onReachStart(() => { 884 this.gridPosition = 0 885 console.info("XXX" + "Grid onReachStart") 886 }) 887 .onReachEnd(() => { 888 this.gridPosition = 2 889 console.info("XXX" + "Grid onReachEnd") 890 }) 891 892 Button('next page') 893 .onClick(() => { // 点击后滑到下一页 894 this.scroller.scrollPage({ next: true }) 895 }) 896 }.width('100%').margin({ top: 5 }) 897 } 898} 899``` 900 901 902 903### 示例3 904 905GridLayoutOptions的使用：irregularIndexes与onGetIrregularSizeByIndex。 906 907```ts 908// xxx.ets 909@Entry 910@Component 911struct GridExample { 912 @State numbers: String[] = ['0', '1', '2', '3', '4'] 913 scroller: Scroller = new Scroller() 914 layoutOptions1: GridLayoutOptions = { 915 regularSize: [1, 1], // 只支持[1, 1] 916 irregularIndexes: [0, 6], // 索引为0和6的GridItem占用一行 917 } 918 919 layoutOptions2: GridLayoutOptions = { 920 regularSize: [1, 1], 921 irregularIndexes: [0, 7], // 索引为0和7的GridItem占用的列数由onGetIrregularSizeByIndex指定 922 onGetIrregularSizeByIndex: (index: number) => { 923 if (index === 0) { 924 return [1, 5] 925 } 926 return [1, index % 6 + 1] 927 } 928 } 929 930 build() { 931 Column({ space: 5 }) { 932 Grid(this.scroller, this.layoutOptions1) { 933 ForEach(this.numbers, (day: string) => { 934 ForEach(this.numbers, (day: string) => { 935 GridItem() { 936 Text(day) 937 .fontSize(16) 938 .backgroundColor(0xF9CF93) 939 .width('100%') 940 .height(80) 941 .textAlign(TextAlign.Center) 942 }.selectable(false) 943 }, (day: string) => day) 944 }, (day: string) => day) 945 } 946 .columnsTemplate('1fr 1fr 1fr 1fr 1fr') 947 .columnsGap(10) 948 .rowsGap(10) 949 .multiSelectable(true) 950 .scrollBar(BarState.Off) 951 .width('90%') 952 .backgroundColor(0xFAEEE0) 953 .height(300) 954 955 Text('scroll').fontColor(0xCCCCCC).fontSize(9).width('90%') 956 // 不使用scroll，需要undefined占位 957 Grid(undefined, this.layoutOptions2) { 958 ForEach(this.numbers, (day: string) => { 959 ForEach(this.numbers, (day: string) => { 960 GridItem() { 961 Text(day) 962 .fontSize(16) 963 .backgroundColor(0xF9CF93) 964 .width('100%') 965 .height(80) 966 .textAlign(TextAlign.Center) 967 } 968 }, (day: string) => day) 969 }, (day: string) => day) 970 } 971 .columnsTemplate('1fr 1fr 1fr 1fr 1fr') 972 .columnsGap(10) 973 .rowsGap(10) 974 .scrollBar(BarState.Off) 975 .width('90%') 976 .backgroundColor(0xFAEEE0) 977 .height(300) 978 }.width('100%').margin({ top: 5 }) 979 } 980} 981``` 982 983 984 985### 示例4 986 987nestedScroll和onScrollFrameBegin的使用。 988 989```ts 990@Entry 991@Component 992struct GridExample { 993 @State colors: number[] = [0xFFC0CB, 0xDA70D6, 0x6B8E23, 0x6A5ACD, 0x00FFFF, 0x00FF7F] 994 @State numbers: number[] = [] 995 @State translateY: number = 0 996 private scroller: Scroller = new Scroller() 997 private gridScroller: Scroller = new Scroller() 998 private touchDown: boolean = false 999 private listTouchDown: boolean = false 1000 private scrolling: boolean = false 1001 1002 aboutToAppear() { 1003 for (let i = 0; i < 100; i++) { 1004 this.numbers.push(i) 1005 } 1006 } 1007 1008 build() { 1009 Stack() { 1010 Column() { 1011 Row() { 1012 Text('Head') 1013 } 1014 1015 Column() { 1016 List({ scroller: this.scroller }) { 1017 ListItem() { 1018 Grid() { 1019 GridItem() { 1020 Text('GoodsTypeList1') 1021 } 1022 .backgroundColor(this.colors[0]) 1023 .columnStart(0) 1024 .columnEnd(1) 1025 1026 GridItem() { 1027 Text('GoodsTypeList2') 1028 } 1029 .backgroundColor(this.colors[1]) 1030 .columnStart(0) 1031 .columnEnd(1) 1032 1033 GridItem() { 1034 Text('GoodsTypeList3') 1035 } 1036 .backgroundColor(this.colors[2]) 1037 .columnStart(0) 1038 .columnEnd(1) 1039 1040 GridItem() { 1041 Text('GoodsTypeList4') 1042 } 1043 .backgroundColor(this.colors[3]) 1044 .columnStart(0) 1045 .columnEnd(1) 1046 1047 GridItem() { 1048 Text('GoodsTypeList5') 1049 } 1050 .backgroundColor(this.colors[4]) 1051 .columnStart(0) 1052 .columnEnd(1) 1053 } 1054 .scrollBar(BarState.Off) 1055 .columnsGap(15) 1056 .rowsGap(10) 1057 .rowsTemplate('1fr 1fr 1fr 1fr 1fr') 1058 .columnsTemplate('1fr') 1059 .width('100%') 1060 .height(200) 1061 } 1062 1063 ListItem() { 1064 Grid(this.gridScroller) { 1065 ForEach(this.numbers, (item: number) => { 1066 GridItem() { 1067 Text(item + '') 1068 .fontSize(16) 1069 .backgroundColor(0xF9CF93) 1070 .width('100%') 1071 .height('100%') 1072 .textAlign(TextAlign.Center) 1073 } 1074 .width('100%') 1075 .height(40) 1076 .shadow({ radius: 10, color: '#909399', offsetX: 1, offsetY: 1 }) 1077 .borderRadius(10) 1078 .translate({ x: 0, y: this.translateY }) 1079 }, (item: string) => item) 1080 } 1081 .columnsTemplate('1fr 1fr') 1082 .friction(0.3) 1083 .columnsGap(15) 1084 .rowsGap(10) 1085 .scrollBar(BarState.Off) 1086 .width('100%') 1087 .height('100%') 1088 .layoutDirection(GridDirection.Column) 1089 .nestedScroll({ 1090 scrollForward: NestedScrollMode.PARENT_FIRST, 1091 scrollBackward: NestedScrollMode.SELF_FIRST 1092 }) 1093 .onTouch((event: TouchEvent) => { 1094 if (event.type == TouchType.Down) { 1095 this.listTouchDown = true 1096 } else if (event.type == TouchType.Up) { 1097 this.listTouchDown = false 1098 } 1099 }) 1100 } 1101 } 1102 .scrollBar(BarState.Off) 1103 .edgeEffect(EdgeEffect.None) 1104 .onTouch((event: TouchEvent) => { 1105 if (event.type == TouchType.Down) { 1106 this.touchDown = true 1107 } else if (event.type == TouchType.Up) { 1108 this.touchDown = false 1109 } 1110 }) 1111 .onScrollFrameBegin((offset: number, state: ScrollState) => { 1112 if (this.scrolling && offset > 0) { 1113 let newOffset = this.scroller.currentOffset().yOffset 1114 if (newOffset >= 590) { 1115 this.gridScroller.scrollBy(0, offset) 1116 return { offsetRemain: 0 } 1117 } else if (newOffset + offset > 590) { 1118 this.gridScroller.scrollBy(0, newOffset + offset - 590) 1119 return { offsetRemain: 590 - newOffset } 1120 } 1121 } 1122 return { offsetRemain: offset } 1123 }) 1124 .onScrollStart(() => { 1125 if (this.touchDown && !this.listTouchDown) { 1126 this.scrolling = true 1127 } 1128 }) 1129 .onScrollStop(() => { 1130 this.scrolling = false 1131 }) 1132 } 1133 .width('100%') 1134 .height('100%') 1135 .padding({ left: 10, right: 10 }) 1136 } 1137 1138 Row() { 1139 Text('Top') 1140 .width(30) 1141 .height(30) 1142 .borderRadius(50) 1143 } 1144 .padding(5) 1145 .borderRadius(50) 1146 .backgroundColor('#ffffff') 1147 .shadow({ radius: 10, color: '#909399', offsetX: 1, offsetY: 1 }) 1148 .margin({ right: 22, bottom: 15 }) 1149 .onClick(() => { 1150 this.scroller.scrollTo({ xOffset: 0, yOffset: 0 }) 1151 this.gridScroller.scrollTo({ xOffset: 0, yOffset: 0 }) 1152 }) 1153 } 1154 .align(Alignment.BottomEnd) 1155 } 1156} 1157``` 1158 1159 1160 1161### 示例5 1162 11631. 设置属性editMode\(true\)设置Grid是否进入编辑模式，进入编辑模式可以拖拽Grid组件内部GridItem。 11642. 在[onItemDragStart](#onitemdragstart8)回调中设置拖拽过程中显示的图片。 11653. 在[onItemDrop](#onitemdrop8)中获取拖拽起始位置，和拖拽插入位置，并在[onItemDrop](#onitemdrop8)中完成交换数组位置逻辑。 1166 1167> **说明：** 1168> 1169> 预览器窗口不支持显示拖拽跟手。 1170 1171```ts 1172@Entry 1173@Component 1174struct GridExample { 1175 @State numbers: string[] = [] 1176 scroller: Scroller = new Scroller() 1177 @State text: string = 'drag' 1178 1179 @Builder pixelMapBuilder() { //拖拽过程样式 1180 Column() { 1181 Text(this.text) 1182 .fontSize(16) 1183 .backgroundColor(0xF9CF93) 1184 .width(80) 1185 .height(80) 1186 .textAlign(TextAlign.Center) 1187 } 1188 } 1189 1190 aboutToAppear() { 1191 for (let i = 1;i <= 15; i++) { 1192 this.numbers.push(i + '') 1193 } 1194 } 1195 1196 changeIndex(index1: number, index2: number) { //交换数组位置 1197 let temp: string; 1198 temp = this.numbers[index1]; 1199 this.numbers[index1] = this.numbers[index2]; 1200 this.numbers[index2] = temp; 1201 } 1202 1203 build() { 1204 Column({ space: 5 }) { 1205 Grid(this.scroller) { 1206 ForEach(this.numbers, (day: string) => { 1207 GridItem() { 1208 Text(day) 1209 .fontSize(16) 1210 .backgroundColor(0xF9CF93) 1211 .width(80) 1212 .height(80) 1213 .textAlign(TextAlign.Center) 1214 } 1215 }) 1216 } 1217 .columnsTemplate('1fr 1fr 1fr') 1218 .columnsGap(10) 1219 .rowsGap(10) 1220 .width('90%') 1221 .backgroundColor(0xFAEEE0) 1222 .height(300) 1223 .editMode(true) //设置Grid是否进入编辑模式，进入编辑模式可以拖拽Grid组件内部GridItem 1224 .onItemDragStart((event: ItemDragInfo, itemIndex: number) => { //第一次拖拽此事件绑定的组件时，触发回调。 1225 this.text = this.numbers[itemIndex] 1226 return this.pixelMapBuilder() //设置拖拽过程中显示的图片。 1227 }) 1228 .onItemDrop((event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => { //绑定此事件的组件可作为拖拽释放目标，当在本组件范围内停止拖拽行为时，触发回调。 1229 // isSuccess=false时，说明drop的位置在grid外部；insertIndex > length时，说明有新增元素的事件发生 1230 if (!isSuccess || insertIndex >= this.numbers.length) { 1231 return 1232 } 1233 console.info('beixiang' + itemIndex + '', insertIndex + '') //itemIndex拖拽起始位置，insertIndex拖拽插入位置 1234 this.changeIndex(itemIndex, insertIndex) 1235 }) 1236 }.width('100%').margin({ top: 5 }) 1237 } 1238} 1239``` 1240 1241示例图： 1242 1243网格子组件开始拖拽： 1244 1245 1246 1247网格子组件拖拽过程中： 1248 1249 1250 1251网格子组件1与子组件6拖拽交换位置后： 1252 1253 1254 1255### 示例6 1256 1257layoutDirection、maxcount、minCount、cellLength的使用。 1258 1259```ts 1260@Entry 1261@Component 1262struct GridExample { 1263 @State numbers: string[] = [] 1264 1265 aboutToAppear() { 1266 for (let i = 1; i <= 30; i++) { 1267 this.numbers.push(i + '') 1268 } 1269 } 1270 1271 build() { 1272 Scroll() { 1273 Column({ space: 5 }) { 1274 Blank() 1275 Text('rowsTemplate、columnsTemplate都不设置layoutDirection、maxcount、minCount、cellLength才生效') 1276 .fontSize(15).fontColor(0xCCCCCC).width('90%') 1277 Grid() { 1278 ForEach(this.numbers, (day: string) => { 1279 GridItem() { 1280 Text(day).fontSize(16).backgroundColor(0xF9CF93) 1281 }.width(40).height(80).borderWidth(2).borderColor(Color.Red) 1282 }, (day: string) => day) 1283 } 1284 .height(300) 1285 .columnsGap(10) 1286 .rowsGap(10) 1287 .backgroundColor(0xFAEEE0) 1288 .maxCount(6) 1289 .minCount(2) 1290 .cellLength(0) 1291 .layoutDirection(GridDirection.Row) 1292 } 1293 .width('90%').margin({ top: 5, left: 5, right: 5 }) 1294 .align(Alignment.Center) 1295 } 1296 } 1297} 1298``` 1299 1300 1301 1302### 示例7 1303 1304双指缩放修改Grid列数。 1305 1306```ts 1307// xxx.ets 1308@Entry 1309@Component 1310struct GridExample { 1311 @State numbers: String[] = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15', '16', '17', '18', '19'] 1312 @State columns: number = 2 1313 1314 aboutToAppear() { 1315 let lastCount = AppStorage.get<number>('columnsCount') 1316 if (typeof lastCount != 'undefined') { 1317 this.columns = lastCount 1318 } 1319 } 1320 1321 build() { 1322 Column({ space: 5 }) { 1323 Row() { 1324 Text('双指缩放改变列数') 1325 .height('5%') 1326 .margin({ top: 10, left: 20 }) 1327 } 1328 1329 Grid() { 1330 ForEach(this.numbers, (day: string) => { 1331 ForEach(this.numbers, (day: string) => { 1332 GridItem() { 1333 Text(day) 1334 .fontSize(16) 1335 .backgroundColor(0xF9CF93) 1336 .width('100%') 1337 .height(80) 1338 .textAlign(TextAlign.Center) 1339 } 1340 }, (day: string) => day) 1341 }, (day: string) => day) 1342 } 1343 .columnsTemplate('1fr '.repeat(this.columns)) 1344 .columnsGap(10) 1345 .rowsGap(10) 1346 .width('90%') 1347 .scrollBar(BarState.Off) 1348 .backgroundColor(0xFAEEE0) 1349 .height('100%') 1350 .cachedCount(3) 1351 // 切换列数item位置重排动画 1352 .animation({ 1353 duration: 300, 1354 curve: Curve.Smooth 1355 }) 1356 .priorityGesture( 1357 PinchGesture() 1358 .onActionEnd((event: GestureEvent) => { 1359 console.info('end scale:' + event.scale) 1360 // 手指分开，减少列数以放大Item，触发阈值可以自定义，示例为2 1361 if (event.scale > 2) { 1362 this.columns-- 1363 } else if (event.scale < 0.6) { 1364 this.columns++ 1365 } 1366 // 可以根据设备屏幕宽度设定最大和最小列数，此处以最小1列最大4列为例 1367 this.columns = Math.min(4, Math.max(1, this.columns)); 1368 AppStorage.setOrCreate<number>('columnsCount', this.columns) 1369 }) 1370 ) 1371 }.width('100%').margin({ top: 5 }) 1372 } 1373} 1374``` 1375 1376 1377 1378### 示例8 1379属性[columnsTemplate](#columnstemplate)中auto-fill、auto-fit和auto-stretch的使用示例 1380 1381```ts 1382@Entry 1383@Component 1384struct GridColumnsTemplate { 1385 data: number[] = [0, 1, 2, 3, 4, 5] 1386 data1: number[] = [0, 1, 2, 3, 4, 5] 1387 data2: number[] = [0, 1, 2, 3, 4, 5] 1388 1389 build() { 1390 Column({ space: 10 }) { 1391 Text('auto-fill 根据设定的列宽自动计算列数').width('90%') 1392 Grid() { 1393 ForEach(this.data, (item: number) => { 1394 GridItem() { 1395 Text('N' + item).height(80) 1396 } 1397 .backgroundColor(Color.Orange) 1398 }) 1399 } 1400 .width('90%') 1401 .border({ width: 1, color: Color.Black }) 1402 .columnsTemplate('repeat(auto-fill, 70)') 1403 .columnsGap(10) 1404 .rowsGap(10) 1405 .height(150) 1406 1407 Text('auto-fit 先根据设定的列宽计算列数，余下的空间会均分到每一列中').width('90%') 1408 Grid() { 1409 ForEach(this.data1, (item: number) => { 1410 GridItem() { 1411 Text('N' + item).height(80) 1412 } 1413 .backgroundColor(Color.Orange) 1414 }) 1415 } 1416 .width('90%') 1417 .border({ width: 1, color: Color.Black }) 1418 .columnsTemplate('repeat(auto-fit, 70)') 1419 .columnsGap(10) 1420 .rowsGap(10) 1421 .height(150) 1422 1423 Text('auto-stretch 先根据设定的列宽计算列数，余下的空间会均分到每个列间距中').width('90%') 1424 Grid() { 1425 ForEach(this.data2, (item: number) => { 1426 GridItem() { 1427 Text('N' + item).height(80) 1428 } 1429 .backgroundColor(Color.Orange) 1430 }) 1431 } 1432 .width('90%') 1433 .border({ width: 1, color: Color.Black }) 1434 .columnsTemplate('repeat(auto-stretch, 70)') 1435 .columnsGap(10) 1436 .rowsGap(10) 1437 .height(150) 1438 } 1439 .width('100%') 1440 .height('100%') 1441 } 1442} 1443``` 1444 1445 1446 1447### 示例9 1448下面的Grid中包含两列，每列中的GridItem包括高度确定的两个Column和一个高度不确定的Text共三个子组件。 1449 1450在默认情况下，左右两个GridItem的高度可能是不同的；在设置了Grid的[alignItems](#alignitems12)属性为GridItemAlignment.STRETCH后，一行左右两个GridItem中原本高度较小的GridItem会以另一个高度较大的GridItem的高度作为自己的高度。 1451 1452```ts 1453@Entry 1454@Component 1455struct Index { 1456 @State data: number[] = []; 1457 @State items: number[] = []; 1458 1459 aboutToAppear(): void { 1460 for (let i = 0; i < 100; i++) { 1461 this.data.push(i) 1462 this.items.push(this.getSize()) 1463 } 1464 } 1465 1466 getSize() { 1467 let ret = Math.floor(Math.random() * 5) 1468 return Math.max(1, ret) 1469 } 1470 1471 build() { 1472 Column({ space: 10 }) { 1473 Text('Grid alignItems示例代码') 1474 1475 Grid() { 1476 ForEach(this.data, (item: number) => { 1477 // GridItem和Column不设置高度，默认会自适应子组件大小，设置STRETCH的场景下，会变成与当前行最高节点同高。 1478 // 若设置高度，则会保持已设置的高度，不会与当前行最高节点同高。 1479 GridItem() { 1480 Column() { 1481 Column().height(100).backgroundColor('#D5D5D5').width('100%') 1482 // 中间的Text设置flexGrow(1)来自适应填满父组件的空缺 1483 Text('这是一段文字。'.repeat(this.items[item])) 1484 .flexGrow(1).width('100%').align(Alignment.TopStart) 1485 .backgroundColor('#F7F7F7') 1486 Column().height(50).backgroundColor('#707070').width('100%') 1487 } 1488 } 1489 .border({ color: Color.Black, width: 1 }) 1490 }) 1491 } 1492 .columnsGap(10) 1493 .rowsGap(5) 1494 .columnsTemplate('1fr 1fr') 1495 .width('80%') 1496 .height('100%') 1497 // Grid设置alignItems为STRETCH，以当前行最高的GridItem的高度为其他GridItem的高度。 1498 .alignItems(GridItemAlignment.STRETCH) 1499 .scrollBar(BarState.Off) 1500 } 1501 .height('100%') 1502 .width('100%') 1503 } 1504} 1505 1506``` 1507
