1# Scroll 2 3可滚动的容器组件，当子组件的布局尺寸超过父组件的尺寸时，内容可以滚动。 4 5> **说明：** 6> - 该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 7> - 该组件嵌套List子组件滚动时，若List不设置宽高，则默认全部加载，在对性能有要求的场景下建议指定List的宽高。 8> - 该组件滚动的前提是主轴方向大小小于内容大小。 9> - Scroll组件[通用属性clip](ts-universal-attributes-sharp-clipping.md)的默认值为true。 10 11 12## 子组件 13 14支持单个子组件。 15 16 17## 接口 18 19Scroll(scroller?: Scroller) 20 21**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 22 23**系统能力：** SystemCapability.ArkUI.ArkUI.Full 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| -------- | -------- | -------- | -------- | 29| scroller | [Scroller](#scroller) | 否 | 可滚动组件的控制器。用于与可滚动组件进行绑定。 | 30 31## 属性 32 33除支持[通用属性](ts-universal-attributes-size.md)和[滚动组件通用属性](ts-container-scrollable-common.md#属性)外，还支持以下属性： 34 35### scrollable 36 37scrollable(value: ScrollDirection) 38 39设置滚动方向。 40 41**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 42 43**系统能力：** SystemCapability.ArkUI.ArkUI.Full 44 45**参数：** 46 47| 参数名 | 类型 | 必填 | 说明 | 48| ------ | ------------------------------------------- | ---- | ----------------------------------------------- | 49| value | [ScrollDirection](#scrolldirection枚举说明) | 是 | 滚动方向。<br/>默认值：ScrollDirection.Vertical | 50 51### scrollBar 52 53scrollBar(barState: BarState) 54 55设置滚动条状态。如果容器组件无法滚动，则滚动条不显示。如果容器组件的子组件大小为无穷大，则滚动条不支持拖动和伴随滚动。 56 57从API version 10开始，当滚动组件存在圆角时，为避免滚动条被圆角截断，滚动条会自动计算距顶部和底部的避让距离。 58 59**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 60 61**系统能力：** SystemCapability.ArkUI.ArkUI.Full 62 63**参数：** 64 65| 参数名 | 类型 | 必填 | 说明 | 66| -------- | ----------------------------------------- | ---- | -------------------------------------- | 67| barState | [BarState](ts-appendix-enums.md#barstate) | 是 | 滚动条状态。<br/>默认值：BarState.Auto | 68 69### scrollBarColor 70 71scrollBarColor(color: Color | number | string) 72 73设置滚动条的颜色。 74 75**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 76 77**系统能力：** SystemCapability.ArkUI.ArkUI.Full 78 79**参数：** 80 81| 参数名 | 类型 | 必填 | 说明 | 82| ------ | ------------------------------------------------------------ | ---- | -------------- | 83| color | [Color](ts-appendix-enums.md#color) \| number \| string | 是 | 滚动条的颜色。<br/>默认值：'\#182431'（40%不透明度） | 84 85### scrollBarWidth 86 87scrollBarWidth(value: number | string) 88 89设置滚动条的宽度，不支持百分比设置。宽度设置后，滚动条正常状态和按压状态宽度均为滚动条的宽度值。如果滚动条的宽度超过Scroll组件主轴方向的高度，则滚动条的宽度会变为默认值。 90 91**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 92 93**系统能力：** SystemCapability.ArkUI.ArkUI.Full 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| ------ | -------------------------- | ---- | ----------------------------------------- | 99| value | number \| string | 是 | 滚动条的宽度。<br/>默认值：4<br/>单位：vp | 100 101### scrollSnap<sup>10+</sup> 102 103scrollSnap(value: ScrollSnapOptions) 104 105设置Scroll组件的限位滚动模式。 106 107**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 108 109**系统能力：** SystemCapability.ArkUI.ArkUI.Full 110 111**参数：** 112 113| 参数名 | 类型 | 必填 | 说明 | 114| ------ | ----------------------------------------- | ---- | -------------------------- | 115| value | [ScrollSnapOptions](#scrollsnapoptions10) | 是 | Scroll组件的限位滚动模式。 | 116 117### edgeEffect 118 119edgeEffect(edgeEffect: EdgeEffect, options?: EdgeEffectOptions) 120 121设置边缘滑动效果。 122 123**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 124 125**系统能力：** SystemCapability.ArkUI.ArkUI.Full 126 127**参数：** 128 129| 参数名 | 类型 | 必填 | 说明 | 130| --------------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | 131| edgeEffect | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | 是 | Scroll组件的边缘滑动效果，支持弹簧效果和阴影效果。<br/>默认值：EdgeEffect.None | 132| options<sup>11+</sup> | [EdgeEffectOptions](ts-container-scrollable-common.md#edgeeffectoptions11对象说明) | 否 | 组件内容大小小于组件自身时，是否开启滑动效果。设置为{ alwaysEnabled: true }会开启滑动效果，{ alwaysEnabled: false }不开启。<br/>默认值：{ alwaysEnabled: true } | 133 134### enableScrollInteraction<sup>10+</sup> 135 136enableScrollInteraction(value: boolean) 137 138设置是否支持滚动手势，当设置为false时，无法通过手指或者鼠标滚动，但不影响控制器的滚动接口。 139 140**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 141 142**系统能力：** SystemCapability.ArkUI.ArkUI.Full 143 144**参数：** 145 146| 参数名 | 类型 | 必填 | 说明 | 147| ------ | ------- | ---- | ----------------------------------- | 148| value | boolean | 是 | 是否支持滚动手势。<br/>默认值：true | 149 150### nestedScroll<sup>10+</sup> 151 152nestedScroll(value: NestedScrollOptions) 153 154设置向前向后两个方向上的嵌套滚动模式，实现与父组件的滚动联动。 155 156**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 157 158**系统能力：** SystemCapability.ArkUI.ArkUI.Full 159 160**参数：** 161 162| 参数名 | 类型 | 必填 | 说明 | 163| ------ | ----------------------------------------------------- | ---- | -------------- | 164| value | [NestedScrollOptions](ts-container-scrollable-common.md#nestedscrolloptions10对象说明) | 是 | 嵌套滚动选项。<br/>默认值：{ scrollForward: NestedScrollMode.SELF_ONLY, scrollBackward: NestedScrollMode.SELF_ONLY }| 165 166### friction<sup>10+</sup> 167 168friction(value: number | Resource) 169 170设置摩擦系数，手动划动滚动区域时生效，只对惯性滚动过程有影响，对惯性滚动过程中的链式效果有间接影响。设置为小于等于0的值时，按默认值处理 171 172**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 173 174**系统能力：** SystemCapability.ArkUI.ArkUI.Full 175 176**参数：** 177 178| 参数名 | 类型 | 必填 | 说明 | 179| ------ | ---------------------------------------------------- | ---- | --------------------------------------------------------- | 180| value | number \| [Resource](ts-types.md#resource) | 是 | 摩擦系数。<br/>默认值：非可穿戴设备为0.6，可穿戴设备为0.9。<br/>从API version 11开始，非可穿戴设备默认值为0.7。<br/>从API version 12开始，非可穿戴设备默认值为0.75。 | 181 182### enablePaging<sup>11+</sup> 183 184enablePaging(value: boolean) 185 186设置是否支持划动翻页。如果同时设置了划动翻页enablePaging和限位滚动scrollSnap，则scrollSnap优先生效，enablePaging不生效。 187 188**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 189 190**系统能力：** SystemCapability.ArkUI.ArkUI.Full 191 192**参数：** 193 194| 参数名 | 类型 | 必填 | 说明 | 195| ------ | ------- | ---- | ------------------------------------- | 196| value | boolean | 是 | 是否支持划动翻页。设置为true支持滑动翻页，false不支持。 <br/>默认值：false | 197 198### initialOffset<sup>12+</sup> 199 200initialOffset(value: OffsetOptions) 201 202设置初始滚动偏移量。只在首次布局时生效，后续动态修改该属性值不生效。 203 204**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 205 206**系统能力：** SystemCapability.ArkUI.ArkUI.Full 207 208**参数：** 209 210| 参数名 | 类型 | 必填 | 说明 | 211| ------ | ------- | ---- | ------------------------------------- | 212| value | [OffsetOptions](#offsetoptions12对象说明) | 是 |当输入的大小为百分比时，初始滚动偏移量为Scroll组件主轴方向大小与百分比数值之积。| 213 214## ScrollDirection枚举说明 215 216**系统能力：** SystemCapability.ArkUI.ArkUI.Full 217 218| 名称 | 说明 | 219| ---------- | ------------------------ | 220| Horizontal | 仅支持水平方向滚动。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 221| Vertical | 仅支持竖直方向滚动。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 222| None | 不可滚动。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 223| Free<sup>(deprecated) </sup> | 支持竖直或水平方向滚动<br/> 从API version 9开始废弃。| 224 225## ScrollSnapOptions<sup>10+</sup> 226 227**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 228 229**系统能力：** SystemCapability.ArkUI.ArkUI.Full 230 231| 名称 | 类型 | 必填 | 说明 | 232| ---------- | --------------------|-------------------- | -------- | 233| snapAlign | [ScrollSnapAlign](ts-container-list.md#scrollsnapalign10枚举说明) | 是 | 设置Scroll组件限位滚动时的对齐方式。<br/>**说明：** <br/>1.该属性默认值为ScrollSnapAlign.NONE。 | 234| snapPagination | [Dimension](ts-types.md#dimension10) \| Array\<Dimension\> | 否 | 设置Scroll组件限位滚动时的限位点，限位点即为Scroll组件能滑动停靠的偏移量。<br/>**说明：** <br/>1.当属性为Dimension时，表示每页的大小，系统会按照该大小来自动计算每个限位点的位置：如当Dimension为500时，实际的限位点即为[0,500,1000,1500,...]。<br/>2.当属性为Array\<Dimension\>时，每个Dimension代表限位点的位置。每个Dimension的范围为[0,可滑动距离]，0和可滑动距离的底部自动成为限位点。<br/>3.当该属性不填或者Dimension为小于等于0的输入时，按异常值，无限位滚动处理。当该属性值为Array\<Dimension\>数组时，数组中的数值必须为单调递增。<br/>4.当输入为百分比时，实际的大小为Scroll组件的视口与百分比数值之积。 | 235| enableSnapToStart | boolean | 否 | 在Scroll组件限位滚动模式下，该属性设置为false后，允许Scroll在开头和第一个限位点间自由滑动。<br/>**说明：** <br/>1.该属性值默认为true。<br/>2.该属性仅当snapPagination属性为Array\<Dimension\>时生效，不支持Dimension。 | 236| enableSnapToEnd | boolean | 否 | 在Scroll组件限位滚动模式下，该属性设置为false后，允许Scroll在最后一个限位点和末尾间自由滑动。<br/>**说明：** <br/>1.该属性值默认为true。<br/>2.该属性仅当snapPagination属性为Array\<Dimension\>时生效，不支持Dimension。 | 237 238## 事件 239 240除支持[通用事件](ts-universal-events-click.md)和[滚动组件通用事件](ts-container-scrollable-common.md#事件)外，还支持以下事件： 241> **说明：** 242> 243> 不支持滚动组件通用事件中的[onWillScroll](ts-container-scrollable-common.md#onwillscroll12)、[onDidScroll](ts-container-scrollable-common.md#ondidscroll12)事件。 244 245 246### onScrollFrameBegin<sup>9+</sup> 247 248onScrollFrameBegin(event: (offset: number, state: ScrollState) => { offsetRemain: number; }) 249 250每帧开始滚动时触发，事件参数传入即将发生的滚动量，事件处理函数中可根据应用场景计算实际需要的滚动量并作为事件处理函数的返回值返回，Scroll将按照返回值的实际滚动量进行滚动。 251 252支持offsetRemain为负值。 253 254若通过onScrollFrameBegin事件和scrollBy方法实现容器嵌套滚动，需设置子滚动节点的EdgeEffect为None。如Scroll嵌套List滚动时，List组件的edgeEffect属性需设置为EdgeEffect.None。 255 256触发该事件的条件： 257 2581、滚动组件触发滚动时触发，包括键鼠操作等其他触发滚动的输入设置。<br/>2、调用控制器接口时不触发。<br/>3、越界回弹不触发。<br/>4、拖动滚动条不触发。 259 260**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 261 262**系统能力：** SystemCapability.ArkUI.ArkUI.Full 263 264**参数：** 265 266| 参数名 | 类型 | 必填 | 说明 | 267| ------ | ------------------------------------------------------- | ---- | -------------------------- | 268| offset | number | 是 | 即将发生的滑动量，单位vp。 | 269| state | [ScrollState](ts-container-list.md#scrollstate枚举说明) | 是 | 当前滑动状态。 | 270 271**返回值：** 272 273| 类型 | 说明 | 274| ------------------------ | -------------------- | 275| { offsetRemain: number } | 实际滑动量，单位vp。 | 276 277### onScroll<sup>(deprecated)</sup> 278 279onScroll(event: (xOffset: number, yOffset: number) => void) 280 281滚动事件回调，返回滚动时水平、竖直方向偏移量，单位vp。 282 283触发该事件的条件 ： 284 2851、滚动组件触发滚动时触发，支持键鼠操作等其他触发滚动的输入设置。 286 2872、通过滚动控制器API接口调用。 288 2893、越界回弹。 290 291从API version12开始废弃不再使用，推荐使用[onWillScroll](#onwillscroll12)事件替代。 292 293**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 294 295**系统能力：** SystemCapability.ArkUI.ArkUI.Full 296 297**参数：** 298 299| 参数名 | 类型 | 必填 | 说明 | 300| ------- | --------------------------------------------------------- | ---- | ---------------------- | 301| xOffset | number | 是 | 每帧滚动时水平方向的偏移量，Scroll的内容向左滚动时偏移量为正，向右滚动时偏移量为负。<br/>单位vp。 | 302| yOffset | number | 是 | 每帧滚动时竖直方向的偏移量，Scroll的内容向上滚动时偏移量为正，向下滚动时偏移量为负。<br/>单位vp。 | 303 304### onWillScroll<sup>12+</sup> 305 306onWillScroll(handler: ScrollOnWillScrollCallback) 307 308滚动事件回调，Scroll滚动前触发。 309 310回调当前帧将要滚动的偏移量和当前滚动状态和滚动操作来源，其中回调的偏移量为计算得到的将要滚动的偏移量值，并非最终实际滚动偏移。可以通过该回调返回值指定Scroll将要滚动的偏移。 311 312触发该事件的条件 ： 313 3141、滚动组件触发滚动时触发，支持键鼠操作等其他触发滚动的输入设置。 315 3162、通过滚动控制器API接口调用。 317 3183、越界回弹。 319 320**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 321 322**系统能力：** SystemCapability.ArkUI.ArkUI.Full 323 324**参数：** 325 326| 参数名 | 类型 | 必填 | 说明 | 327| ------- | --------------------------------------------------------- | ---- | ---------------------- | 328| handler | [ScrollOnWillScrollCallback](#scrollonwillscrollcallback12) | 是 | Scroll滚动前触发的回调。 | 329 330### onDidScroll<sup>12+</sup> 331 332onDidScroll(handler: ScrollOnScrollCallback) 333 334滚动事件回调，Scroll滚动时触发。 335 336返回当前帧滚动的偏移量和当前滚动状态。 337 338触发该事件的条件 ： 339 3401、滚动组件触发滚动时触发，支持键鼠操作等其他触发滚动的输入设置。 341 3422、通过滚动控制器API接口调用。 343 3443、越界回弹。 345 346**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 347 348**系统能力：** SystemCapability.ArkUI.ArkUI.Full 349 350**参数：** 351 352| 参数名 | 类型 | 必填 | 说明 | 353| ------- | --------------------------------------------------------- | ---- | ---------------------- | 354| handler | [ScrollOnScrollCallback](#scrollonscrollcallback12) | 是 | Scroll滚动时触发的回调 | 355 356### onScrollEdge 357 358onScrollEdge(event: (side: Edge) => void) 359 360滚动到边缘事件回调。 361 362触发该事件的条件 ： 363 3641、滚动组件滚动到边缘时触发，支持键鼠操作等其他触发滚动的输入设置。<br/>2、通过滚动控制器API接口调用。<br/>3、越界回弹。 365 366**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 367 368**系统能力：** SystemCapability.ArkUI.ArkUI.Full 369 370**参数：** 371 372| 参数名 | 类型 | 必填 | 说明 | 373| ------ | --------------------------------- | ---- | ------------------ | 374| side | [Edge](ts-appendix-enums.md#edge) | 是 | 滚动到的边缘位置。 | 375 376### onScrollEnd<sup>(deprecated) </sup> 377 378onScrollEnd(event: () => void) 379 380滚动停止事件回调。 381 382触发该事件的条件 ： 383 3841、滚动组件触发滚动后停止，支持键鼠操作等其他触发滚动的输入设置。<br/>2、通过滚动控制器API接口调用后停止，带过渡动效。 385 386该事件从API version 9开始废弃，使用onScrollStop事件替代。 387 388**系统能力：** SystemCapability.ArkUI.ArkUI.Full 389 390### onScrollStart<sup>9+</sup> 391 392onScrollStart(event: () => void) 393 394滚动开始时触发。手指拖动Scroll或拖动Scroll的滚动条触发的滚动开始时，会触发该事件。使用[Scroller](#scroller)滚动控制器触发的带动画的滚动，动画开始时会触发该事件。 395 396触发该事件的条件 ： 397 3981、滚动组件开始滚动时触发，支持键鼠操作等其他触发滚动的输入设置。<br/>2、通过滚动控制器API接口调用后开始，带过渡动效。 399 400**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 401 402**系统能力：** SystemCapability.ArkUI.ArkUI.Full 403 404### onScrollStop<sup>9+</sup> 405 406onScrollStop(event: () => void) 407 408滚动停止时触发。手拖动Scroll或拖动Scroll的滚动条触发的滚动，手离开屏幕并且滚动停止时会触发该事件。使用[Scroller](#scroller)滚动控制器触发的带动画的滚动，动画停止时会触发该事件。 409 410触发该事件的条件 ： 411 4121、滚动组件触发滚动后停止，支持键鼠操作等其他触发滚动的输入设置。<br/>2、通过滚动控制器API接口调用后开始，带过渡动效。 413 414**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 415 416**系统能力：** SystemCapability.ArkUI.ArkUI.Full 417 418## ScrollOnScrollCallback<sup>12+</sup> 419 420type ScrollOnScrollCallback = (xOffset: number, yOffset: number, scrollState: ScrollState) => void 421 422Scroll滚动时触发的回调。 423 424**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 425 426**系统能力：** SystemCapability.ArkUI.ArkUI.Full 427 428| 参数名 | 类型 | 必填 | 说明 | 429| ----------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 430| xOffset | number | 是 | 每帧滚动时水平方向的偏移量，Scroll中的内容向左滚动时偏移量为正，向右滚动时偏移量为负。<br/>单位vp。 | 431| yOffset | number | 是 | 每帧滚动时竖直方向的偏移量，Scroll中的内容向上滚动时偏移量为正，向下滚动时偏移量为负。<br/>单位vp。 | 432| scrollState | [ScrollState](ts-container-list.md#scrollstate枚举说明) | 是 | 当前滚动状态。 | 433 434> **说明：** 435> 436> 若通过onScrollFrameBegin事件和scrollBy方法实现容器嵌套滚动，需设置子滚动节点的EdgeEffect为None。如Scroll嵌套List滚动时，List组件的edgeEffect属性需设置为EdgeEffect.None。 437 438## ScrollOnWillScrollCallback<sup>12+</sup> 439 440type ScrollOnWillScrollCallback = (xOffset: number, yOffset: number, scrollState: ScrollState, scrollSource: ScrollSource) => void | OffsetResult 441 442Scroll滚动前触发的回调。 443 444**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 445 446**系统能力：** SystemCapability.ArkUI.ArkUI.Full 447 448| 参数名 | 类型 | 必填 | 说明 | 449| ----------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 450| xOffset | number | 是 | 每帧滚动时水平方向的偏移量，Scroll中的内容向左滚动时偏移量为正，向右滚动时偏移量为负。<br/>单位vp。 | 451| yOffset | number | 是 | 每帧滚动时竖直方向的偏移量，Scroll中的内容向上滚动时偏移量为正，向下滚动时偏移量为负。<br/>单位vp。 | 452| scrollState | [ScrollState](ts-container-list.md#scrollstate枚举说明) | 是 | 当前滚动状态。 | 453| scrollSource | [ScrollSource](ts-appendix-enums.md#scrollsource12) | 是 | 当前滚动操作的来源。 | 454 455**返回值：** 456 457| 类型 | 说明 | 458| ------------------------------------------------------------ | ------------------------------------------------------------ | 459| void \| [OffsetResult](#offsetresult11) | 返回OffsetResult时按照开发者指定的偏移量滚动；不返回时按回调参数(xOffset，yOffset)滚动。 | 460 461## Scroller 462 463可滚动容器组件的控制器，可以将此组件绑定至容器组件，然后通过它控制容器组件的滚动，同一个控制器不可以控制多个容器组件，目前支持绑定到List、Scroll、ScrollBar、Grid、WaterFlow上。 464 465>**说明：** 466> 467>1、Scroller控制器与滚动容器组件的绑定发生在组件创建阶段。<br/> 468>2、Scroller控制器与滚动容器组件绑定后才可以正常调用Scroller方法，否则根据调用接口不同会不生效或者抛异常。<br/> 469>3、以[aboutToAppear](ts-custom-component-lifecycle.md#abouttoappear)为例，aboutToAppear在创建自定义组件的新实例后，在执行其build()方法之前执行。因此如果滚动组件在自定义组件build内，在该自定义组件aboutToAppear执行时，内部滚动组件还没有创建，是不能正常调用上述Scroller方法的。<br/> 470>4、以[onAppear](ts-universal-events-show-hide.md#onappear)为例，组件挂载显示后触发此回调。因此在滚动组件的onAppear回调执行时，滚动组件已经创建并已经和Scroller绑定成功，是可以正常调用Scroller方法的。 471 472### 导入对象 473 474``` 475scroller: Scroller = new Scroller() 476``` 477 478### constructor 479 480constructor() 481 482Scroller的构造函数。 483 484**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 485 486**系统能力：** SystemCapability.ArkUI.ArkUI.Full 487 488### scrollTo 489 490scrollTo(value: { xOffset: number | string, yOffset: number | string, animation?: ScrollAnimationOptions | boolean }) 491 492 493滑动到指定位置。 494 495**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 496 497**系统能力：** SystemCapability.ArkUI.ArkUI.Full 498 499**参数：** 500 501| 参数名 | 类型 | 必填 | 说明 | 502| --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 503| xOffset | number \| string | 是 | 水平滑动偏移。<br/>**说明：** <br/>该参数值不支持设置百分比。<br/>当值小于0时，不带动画的滚动，按0处理。带动画的滚动，默认滚动到起始位置后停止，可通过设置animation参数，使滚动在越界时启动回弹动画。<br/>仅滚动轴为x轴时生效。 | 504| yOffset | number \| string | 是 | 垂直滑动偏移。<br/>**说明：** <br/>该参数值不支持设置百分比。<br/>当值小于0时，不带动画的滚动，按0处理。带动画的滚动，默认滚动到起始位置后停止，可通过设置animation参数，使滚动在越界时启动回弹动画。<br/>仅滚动轴为y轴时生效。 | 505| animation | [ScrollAnimationOptions](#scrollanimationoptions12)<sup>12+</sup> \| boolean<sup>10+ </sup> | 否 | 动画配置。<br/>- ScrollAnimationOptions: 自定义滚动动效。 <br/>- boolean: 使能默认弹簧动效。<br/>默认值：<br/>ScrollAnimationOptions: { duration: 1000, curve: Curve.Ease, canOverScroll: false } <br/>boolean: false<br/>**说明：** <br/>当前List、Scroll、Grid、WaterFlow均支持boolean类型和ICurve曲线。<br/>于API12将原来的 {duration?: number, curve?: [Curve](ts-appendix-enums.md#curve) \| [ICurve](../js-apis-curve.md#icurve)<sup>10+ </sup>} 抽象为了ScrollAnimationOptions接口，并在其中添加了一个参数canOverScroll。 | 506 507 508### scrollEdge 509 510scrollEdge(value: Edge, options?: ScrollEdgeOptions) 511 512滚动到容器边缘，不区分滚动轴方向，Edge.Top和Edge.Start表现相同，Edge.Bottom和Edge.End表现相同。 513Scroll组件默认有动画，Grid、List、WaterFlow组件默认无动画。 514 515**系统能力：** SystemCapability.ArkUI.ArkUI.Full 516 517**参数：** 518 519| 参数名 | 类型 | 必填 | 说明 | 520| ----- | ---- | ---- | --------- | 521| value | [Edge](ts-appendix-enums.md#edge) | 是 | 滚动到的边缘位置。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 522| options<sup>12+</sup> | [ScrollEdgeOptions](#scrolledgeoptions12对象说明) | 否 | 设置滚动到边缘位置的模式。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 523 524### fling<sup>12+</sup> 525 526fling(velocity: number): void 527 528 529滚动类组件开启按传入的初始速度进行惯性滚动。 530 531**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 532 533**系统能力：** SystemCapability.ArkUI.ArkUI.Full 534 535**参数：** 536 537| 参数名 | 类型 | 必填 | 说明 | 538| -------- | -------- | ---- | ------------------------------------------------------------ | 539| velocity | number | 是 | 惯性滚动的初始速度值。单位：vp/s<br/>**说明：**<br/>velocity值设置为0，视为异常值，本次滚动不生效。如果值为正数，则向下滚动；如果值为负数，则向上滚动。 | 540 541**错误码**： 542 543以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)。 544 545| 错误码ID | 错误信息 | 546| ------- | -------- | 547| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 548| 100004 | Controller not bound to component. | 549 550### scrollPage<sup>9+</sup> 551 552scrollPage(value: ScrollPageOptions) 553 554滚动到下一页或者上一页。 555 556**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 557 558**系统能力：** SystemCapability.ArkUI.ArkUI.Full 559 560**参数：** 561 562| 参数名 | 类型 | 必填 | 说明 | 563| ------ | -------------------------------------------------- | ---- | -------------- | 564| value | [ScrollPageOptions](#scrollpageoptions14对象说明) | 是 | 设置翻页模式。 | 565 566### scrollPage<sup>(deprecated)</sup> 567 568scrollPage(value: { next: boolean, direction?: Axis }) 569 570滚动到下一页或者上一页。从API version 9开始, 该接口不再维护，推荐使用[scrollPage<sup>9+</sup>](#scrollpage9)。 571 572**系统能力：** SystemCapability.ArkUI.ArkUI.Full 573 574**参数：** 575 576| 参数名 | 类型 | 必填 | 说明 | 577| --------- | ------- | ---- | ------------------------------ | 578| next | boolean | 是 | 是否向下翻页。true表示向下翻页，false表示向上翻页。 | 579| direction | [Axis](ts-appendix-enums.md#axis) | 否 | 设置滚动方向为水平或竖直方向。 | 580 581### currentOffset 582 583currentOffset(): OffsetResult 584 585**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 586 587**系统能力：** SystemCapability.ArkUI.ArkUI.Full 588 589| 类型 | 描述 | 590| -------- | -------- | 591| [OffsetResult<sup>11+</sup>](#offsetresult11) | 返回当前的滚动偏移量。<br/>**说明：**<br/>当scroller控制器未绑定容器组件或者容器组件被异常释放时，currentOffset的返回值为空。| 592 593### scrollToIndex 594 595scrollToIndex(value: number, smooth?: boolean, align?: ScrollAlign, options?: ScrollToIndexOptions) 596 597滑动到指定Index，支持设置滑动额外偏移量。 598 599开启smooth动效时，会对经过的所有item进行加载和布局计算，当大量加载item时会导致性能问题。 600 601 602> **说明：** 603> 604> 仅支持Grid、List、WaterFlow组件。 605 606**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 607 608**系统能力：** SystemCapability.ArkUI.ArkUI.Full 609 610**参数：** 611 612| 参数名 | 类型 | 必填 | 说明 | 613| --------------------- | -------- | ---- | ------------------------------------------------------------ | 614| value | number | 是 | 要滑动到的目标元素在当前容器中的索引值。 <br/>**说明：** <br/>value值设置成负值或者大于当前容器子组件的最大索引值，视为异常值，本次跳转不生效。 | 615| smooth | boolean | 否 | 设置滑动到列表项在列表中的索引值时是否有动效，true表示有动效，false表示没有动效。<br/>默认值：false。| 616| align | [ScrollAlign](#scrollalign10枚举说明) | 否 | 指定滑动到的元素与当前容器的对齐方式。<br/>List中的默认值为：ScrollAlign.START。Grid中默认值为：ScrollAlign.AUTO。WaterFlow中的默认值为：ScrollAlign.START。<br/>**说明：** <br/>仅List、Grid、WaterFlow组件支持该参数。 | 617| options<sup>12+</sup> | [ScrollToIndexOptions](#scrolltoindexoptions12对象说明) | 否 | 设置滑动到指定Index的选项，如额外偏移量。<br/>默认值：0，单位：vp。 | 618 619### scrollBy<sup>9+</sup> 620 621scrollBy(dx: Length, dy: Length) 622 623 624滑动指定距离。 625 626 627> **说明：** 628> 629> 支持Scroll、List、Grid、WaterFlow组件。 630 631**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 632 633**系统能力：** SystemCapability.ArkUI.ArkUI.Full 634 635**参数：** 636 637| 参数名 | 类型 | 必填 | 说明 | 638| ----- | ------ | ---- | ----------------- | 639| dx | [Length](ts-types.md#length) | 是 | 水平方向滚动距离，不支持百分比形式。 | 640| dy | [Length](ts-types.md#length) | 是 | 竖直方向滚动距离，不支持百分比形式。 | 641 642### isAtEnd<sup>10+</sup> 643 644isAtEnd(): boolean 645 646查询组件是否滚动到底部。 647 648> **说明：** 649> 650> 支持Scroll、List、Grid、WaterFlow组件。 651 652**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 653 654**系统能力：** SystemCapability.ArkUI.ArkUI.Full 655 656**返回值** 657 658| 类型 | 描述 | 659| ------- | -------- | 660| boolean | true表示组件已经滚动到底部，false表示组件还没滚动到底部。 | 661 662### getItemRect<sup>11+</sup> 663 664getItemRect(index: number): RectResult 665 666获取子组件的大小及相对容器组件的位置。 667 668> **说明：** 669> 670> 支持Scroll、List、Grid、WaterFlow组件。 671 672**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 673 674**系统能力：** SystemCapability.ArkUI.ArkUI.Full 675 676**参数：** 677 678| 参数名 | 类型 | 必填 | 说明 | 679| ----- | ------ | ---- | ----------------- | 680| index | number | 是 | 子组件的索引值。 | 681 682> **说明：** 683> 684> - index必须是当前显示区域显示的子组件的索引值，否则视为非法值。 685> - 非法值返回的大小和位置均为0。 686 687**返回值：** 688 689| 类型 | 说明 | 690| ------------------- | -------- | 691| [RectResult](ts-types.md#rectresult10) | 子组件的大小和相对于组件的位置。<br/>单位：vp。 | 692 693**错误码**： 694 695以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)。 696 697| 错误码ID | 错误信息 | 698| ------- | -------- | 699| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 700| 100004 | Controller not bound to component. | 701### getItemIndex<sup>14+</sup> 702 703getItemIndex(x: number, y: number): number 704 705通过坐标获取子组件的索引。 706 707> **说明：** 708> 709> 支持List、Grid、WaterFlow组件。 710 711**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 712 713**系统能力：** SystemCapability.ArkUI.ArkUI.Full 714 715**参数：** 716 717| 参数名 | 类型 | 必填 | 说明 | 718| ----- | ------ | ---- | ----------------- | 719| x | number | 是 | x轴坐标，单位为vp。 | 720| y | number | 是 | y轴坐标，单位为vp。 | 721 722> **说明：** 723> 724> 非法值返回的索引为-1。 725 726**返回值：** 727 728| 类型 | 说明 | 729| ------------------- | -------- | 730| number | 返回子组件的索引，单位：vp。 | 731 732**错误码**： 733 734以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)。 735 736| 错误码ID | 错误信息 | 737| ------- | -------- | 738| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 739| 100004 |The controller not bound to component. | 740 741## OffsetResult<sup>11+</sup> 742 743**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 744 745**系统能力：** SystemCapability.ArkUI.ArkUI.Full 746 747| 名称 | 类型 | 只读 | 可选 | 说明 | 748| ------- |------- | ---- | ---- | -------------------------------- | 749| xOffset | number | 否 | 否 | 水平滑动偏移。<br/>返回值单位为vp。 | 750| yOffset | number | 否 | 否 | 竖直滑动偏移。<br/>返回值单位为vp。 | 751 752## ScrollAnimationOptions<sup>12+</sup> 753 754**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 755 756**系统能力：** SystemCapability.ArkUI.ArkUI.Full 757 758| 名称 | 类型 | 必填 | 说明 | 759| ----- | ------ | ------ | ----------------- | 760| duration | number | 否 | 设置滚动时长。<br/>默认值：1000<br/>**说明：** <br/>设置为小于0的值时，按默认值显示。 | 761| curve | [Curve](ts-appendix-enums.md#curve) \| [ICurve](../js-apis-curve.md#icurve9) | 否 | 设置滚动曲线。<br/>默认值：Curve.Ease | 762| canOverScroll | boolean | 否 | 设置滚动是否可越界。<br/>默认值：false<br/>**说明：** <br/> 仅在设置为true，且组件的edgeEffect设置为[EdgeEffect.Spring](ts-appendix-enums.md#edgeeffect)时，滚动能够越界，并在越界时启动回弹动画。 | 763 764## ScrollAlign<sup>10+</sup>枚举说明 765 766**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 767 768**系统能力：** SystemCapability.ArkUI.ArkUI.Full 769 770| 名称 | 说明 | 771| ------ | ------------------------------ | 772| START | 首部对齐。指定item首部与List首部对齐。 | 773| CENTER | 居中对齐。指定item主轴方向居中对齐于List。 | 774| END | 尾部对齐。指定item尾部与List尾部对齐。 | 775| AUTO | 自动对齐。<br/>若指定item完全处于显示区，不做调整。否则依照滑动距离最短的原则，将指定item首部对齐或尾部对齐于List,使指定item完全处于显示区。| 776 777## ScrollToIndexOptions<sup>12+</sup>对象说明 778 779**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 780 781**系统能力：** SystemCapability.ArkUI.ArkUI.Full 782 783| 名称 | 类型 | 必填 | 说明 | 784| ----- | ------ | ------ | ----------------- | 785| extraOffset | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 否 | 滑动到指定Index的额外偏移量。 | 786 787## ScrollPageOptions<sup>14+</sup>对象说明 788 789**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 790 791**系统能力：** SystemCapability.ArkUI.ArkUI.Full 792 793| 名称 | 类型 | 必填 | 说明 | 794| --------- | -------- | ---- | ------------------------------------------------------------ | 795| next | boolean | 是 | 是否向下翻页。true表示向下翻页，false表示向上翻页。 | 796| animation | boolean | 否 | 是否开启翻页动画效果。true有动画，false无动画。<br />默认值：false。 | 797 798## OffsetOptions<sup>12+</sup>对象说明 799 800**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 801 802**系统能力：** SystemCapability.ArkUI.ArkUI.Full 803 804| 名称 | 类型 | 必填 | 说明 | 805| ----- | ------| ------- | ----------------- | 806| xOffset | [Dimension](ts-types.md#dimension10) | 否 |水平滑动偏移<br/>默认值：0 | 807| yOffset | [Dimension](ts-types.md#dimension10) | 否 |垂直滑动偏移<br/>默认值：0| 808 809## ScrollEdgeOptions<sup>12+</sup>对象说明 810 811**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 812 813**系统能力：** SystemCapability.ArkUI.ArkUI.Full 814 815| 名称 | 类型 | 必填 | 说明 | 816| --------- | -------- | ---- | ------------------------------------------------------------ | 817| velocity | number | 否 | 设置滚动到容器边缘的固定速度。如果设置小于等于0的值，参数不生效。<br/>默认值：0<br/> 单位： vp/s | 818 819## 示例 820### 示例1（设置scroller控制器） 821该示例展示了Scroll组件部分属性和scroller控制器的使用。 822 823```ts 824// xxx.ets 825import { curves } from '@kit.ArkUI' 826 827@Entry 828@Component 829struct ScrollExample { 830 scroller: Scroller = new Scroller() 831 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 832 833 build() { 834 Stack({ alignContent: Alignment.TopStart }) { 835 Scroll(this.scroller) { 836 Column() { 837 ForEach(this.arr, (item: number) => { 838 Text(item.toString()) 839 .width('90%') 840 .height(150) 841 .backgroundColor(0xFFFFFF) 842 .borderRadius(15) 843 .fontSize(16) 844 .textAlign(TextAlign.Center) 845 .margin({ top: 10 }) 846 }, (item: string) => item) 847 }.width('100%') 848 } 849 .scrollable(ScrollDirection.Vertical) // 滚动方向纵向 850 .scrollBar(BarState.On) // 滚动条常驻显示 851 .scrollBarColor(Color.Gray) // 滚动条颜色 852 .scrollBarWidth(10) // 滚动条宽度 853 .friction(0.6) 854 .edgeEffect(EdgeEffect.None) 855 .onWillScroll((xOffset: number, yOffset: number, scrollState: ScrollState) => { 856 console.info(xOffset + ' ' + yOffset) 857 }) 858 .onScrollEdge((side: Edge) => { 859 console.info('To the edge') 860 }) 861 .onScrollStop(() => { 862 console.info('Scroll Stop') 863 }) 864 865 Button('scroll 150') 866 .height('5%') 867 .onClick(() => { // 点击后下滑指定距离150.0vp 868 this.scroller.scrollBy(0, 150) 869 }) 870 .margin({ top: 10, left: 20 }) 871 Button('scroll 100') 872 .height('5%') 873 .onClick(() => { // 点击后滑动到指定位置，即下滑100.0vp的距离 874 const yOffset: number = this.scroller.currentOffset().yOffset; 875 this.scroller.scrollTo({ xOffset: 0, yOffset: yOffset + 100 }) 876 }) 877 .margin({ top: 60, left: 20 }) 878 Button('scroll 100') 879 .height('5%') 880 .onClick(() => { // 点击后滑动到指定位置，即下滑100.0vp的距离，滑动过程配置有动画 881 let curve = curves.interpolatingSpring(10, 1, 228, 30) //创建一个阶梯曲线 882 const yOffset: number = this.scroller.currentOffset().yOffset; 883 this.scroller.scrollTo({ xOffset: 0, yOffset: yOffset + 100, animation: { duration: 1000, curve: curve } }) 884 }) 885 .margin({ top: 110, left: 20 }) 886 Button('back top') 887 .height('5%') 888 .onClick(() => { // 点击后回到顶部 889 this.scroller.scrollEdge(Edge.Top) 890 }) 891 .margin({ top: 160, left: 20 }) 892 Button('next page') 893 .height('5%') 894 .onClick(() => { // 点击后滑到下一页 895 this.scroller.scrollPage({ next: true ,animation: true }) 896 }) 897 .margin({ top: 210, left: 20 }) 898 Button('fling -3000') 899 .height('5%') 900 .onClick(() => { // 点击后触发初始速度为-3000vp/s的惯性滚动 901 this.scroller.fling(-3000) 902 }) 903 .margin({ top: 260, left: 20 }) 904 Button('scroll to bottom 700') 905 .height('5%') 906 .onClick(() => { // 点击后滑到下边缘，速度值是700vp/s 907 this.scroller.scrollEdge(Edge.Bottom, { velocity: 700 }) 908 }) 909 .margin({ top: 310, left: 20 }) 910 }.width('100%').height('100%').backgroundColor(0xDCDCDC) 911 } 912} 913``` 914 915 916 917### 示例2（嵌套滚动实现方式一） 918该示例使用onScrollFrameBegin事件实现了内层List组件和外层Scroll组件的嵌套滚动。 919```ts 920import { LengthMetrics } from '@kit.ArkUI' 921 922@Entry 923@Component 924struct NestedScroll { 925 @State listPosition: number = 0; // 0代表滚动到List顶部，1代表中间值，2代表滚动到List底部。 926 private arr: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] 927 private scrollerForScroll: Scroller = new Scroller() 928 private scrollerForList: Scroller = new Scroller() 929 930 build() { 931 Flex() { 932 Scroll(this.scrollerForScroll) { 933 Column() { 934 Text("Scroll Area") 935 .width("100%") 936 .height("40%") 937 .backgroundColor(0X330000FF) 938 .fontSize(16) 939 .textAlign(TextAlign.Center) 940 .onClick(() => { 941 this.scrollerForList.scrollToIndex(5, false, ScrollAlign.START, { extraOffset: LengthMetrics.vp(5) }) 942 }) 943 944 List({ space: 20, scroller: this.scrollerForList }) { 945 ForEach(this.arr, (item: number) => { 946 ListItem() { 947 Text("ListItem" + item) 948 .width("100%") 949 .height("100%") 950 .borderRadius(15) 951 .fontSize(16) 952 .textAlign(TextAlign.Center) 953 .backgroundColor(Color.White) 954 }.width("100%").height(100) 955 }, (item: string) => item) 956 } 957 .width("100%") 958 .height("50%") 959 .edgeEffect(EdgeEffect.None) 960 .friction(0.6) 961 .onReachStart(() => { 962 this.listPosition = 0 963 }) 964 .onReachEnd(() => { 965 this.listPosition = 2 966 }) 967 .onScrollFrameBegin((offset: number) => { 968 if ((this.listPosition == 0 && offset <= 0) || (this.listPosition == 2 && offset >= 0)) { 969 this.scrollerForScroll.scrollBy(0, offset) 970 return { offsetRemain: 0 } 971 } 972 this.listPosition = 1 973 return { offsetRemain: offset }; 974 }) 975 976 Text("Scroll Area") 977 .width("100%") 978 .height("40%") 979 .backgroundColor(0X330000FF) 980 .fontSize(16) 981 .textAlign(TextAlign.Center) 982 } 983 } 984 .width("100%").height("100%") 985 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding(20) 986 } 987} 988``` 989 990 991 992### 示例3（嵌套滚动实现方式二） 993该示例使用nestedScroll属性实现了内层List组件和外层Scroll组件的嵌套滚动。 994```ts 995@Entry 996@Component 997struct StickyNestedScroll { 998 @State arr: number[] = [] 999 1000 @Styles 1001 listCard() { 1002 .backgroundColor(Color.White) 1003 .height(72) 1004 .width("100%") 1005 .borderRadius(12) 1006 } 1007 1008 build() { 1009 Scroll() { 1010 Column() { 1011 Text("Scroll Area") 1012 .width("100%") 1013 .height("40%") 1014 .backgroundColor('#0080DC') 1015 .textAlign(TextAlign.Center) 1016 Tabs({ barPosition: BarPosition.Start }) { 1017 TabContent() { 1018 List({ space: 10 }) { 1019 ForEach(this.arr, (item: number) => { 1020 ListItem() { 1021 Text("item" + item) 1022 .fontSize(16) 1023 }.listCard() 1024 }, (item: string) => item) 1025 }.width("100%") 1026 .edgeEffect(EdgeEffect.Spring) 1027 .nestedScroll({ 1028 scrollForward: NestedScrollMode.PARENT_FIRST, 1029 scrollBackward: NestedScrollMode.SELF_FIRST 1030 }) 1031 }.tabBar("Tab1") 1032 1033 TabContent() { 1034 }.tabBar("Tab2") 1035 } 1036 .vertical(false) 1037 .height("100%") 1038 }.width("100%") 1039 } 1040 .edgeEffect(EdgeEffect.Spring) 1041 .friction(0.6) 1042 .backgroundColor('#DCDCDC') 1043 .scrollBar(BarState.Off) 1044 .width('100%') 1045 .height('100%') 1046 } 1047 1048 aboutToAppear() { 1049 for (let i = 0; i < 30; i++) { 1050 this.arr.push(i) 1051 } 1052 } 1053} 1054``` 1055 1056### 示例4（嵌套滚动父组件向子组件传递滚动） 1057该示例使用enableScrollInteraction属性和onScrollFrameBegin事件实现了父组件向子组件传递滚动。 1058```ts 1059@Entry 1060@Component 1061struct NestedScroll { 1062 private headerHeight: number = 0; 1063 private arr: number[] = [] 1064 private scrollerForParent: Scroller = new Scroller() 1065 private scrollerForChild: Scroller = new Scroller() 1066 1067 aboutToAppear(): void { 1068 for (let i = 0; i < 10; i++) { 1069 this.arr.push(i) 1070 } 1071 } 1072 1073 build() { 1074 Scroll(this.scrollerForParent) { 1075 Column() { 1076 Text("Scroll Area") 1077 .width("100%") 1078 .height("40%") 1079 .backgroundColor(0X330000FF) 1080 .fontSize(16) 1081 .textAlign(TextAlign.Center) 1082 .onClick(() => { 1083 this.scrollerForChild.scrollToIndex(5) 1084 }) 1085 .onSizeChange((oldValue: SizeOptions, newValue: SizeOptions) => { 1086 this.headerHeight = newValue.height! as number 1087 }) 1088 List({ space: 20, scroller: this.scrollerForChild }) { 1089 ForEach(this.arr, (item: number) => { 1090 ListItem() { 1091 Text("ListItem" + item) 1092 .width("100%") 1093 .height("100%") 1094 .borderRadius(15) 1095 .fontSize(16) 1096 .textAlign(TextAlign.Center) 1097 .backgroundColor(Color.White) 1098 }.width("100%").height(100) 1099 }, (item: string) => item) 1100 } 1101 .width("100%") 1102 .height("100%") 1103 .edgeEffect(EdgeEffect.None) 1104 .scrollBar(BarState.Off) 1105 .enableScrollInteraction(false) 1106 1107 Text("Scroll Area") 1108 .width("100%") 1109 .height("40%") 1110 .backgroundColor(0X330000FF) 1111 .fontSize(16) 1112 .textAlign(TextAlign.Center) 1113 } 1114 } 1115 .scrollBar(BarState.Off) 1116 .edgeEffect(EdgeEffect.Spring) 1117 .onScrollFrameBegin((offset: number, state: ScrollState) => { 1118 let retOffset = offset; 1119 let currOffset = this.scrollerForParent.currentOffset().yOffset; 1120 let newOffset = currOffset + offset; 1121 if (offset > 0) { 1122 if (this.scrollerForChild.isAtEnd()) { 1123 return { offsetRemain: offset } 1124 } 1125 if (newOffset > this.headerHeight) { 1126 retOffset = this.headerHeight - currOffset 1127 } 1128 this.scrollerForChild.scrollBy(0, offset - retOffset) 1129 } else { 1130 if (this.scrollerForChild.currentOffset().yOffset <= 0) { 1131 return { offsetRemain: offset } 1132 } 1133 if (newOffset < this.headerHeight) { 1134 retOffset = this.headerHeight - currOffset 1135 } 1136 this.scrollerForChild.scrollBy(0, offset - retOffset) 1137 } 1138 return { offsetRemain: retOffset } 1139 }) 1140 .width("100%") 1141 .height("100%") 1142 .backgroundColor(0xDCDCDC) 1143 } 1144} 1145``` 1146 1147### 示例5（设置限位滚动） 1148该示例实现了Scroll组件的限位滚动。 1149```ts 1150@Entry 1151@Component 1152struct Index { 1153 scroller: Scroller = new Scroller; 1154 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] 1155 build() { 1156 Scroll(this.scroller) { 1157 Column() { 1158 ForEach(this.arr, (item: number) => { 1159 Text(item.toString()) 1160 .width('90%') 1161 .height(200) 1162 .backgroundColor(0xFFFFFF) 1163 .borderWidth(1) 1164 .borderColor(Color.Black) 1165 .borderRadius(15) 1166 .fontSize(16) 1167 .textAlign(TextAlign.Center) 1168 }, (item: string) => item) 1169 }.width('100%').backgroundColor(0xDCDCDC) 1170 } 1171 .backgroundColor(Color.Yellow) 1172 .height('100%') 1173 .edgeEffect(EdgeEffect.Spring) 1174 .scrollSnap({snapAlign:ScrollSnapAlign.START, snapPagination:400, enableSnapToStart:true, enableSnapToEnd:true}) 1175 } 1176} 1177``` 1178 1179 1180### 示例6（获取子组件索引） 1181该示例展示了如何获得List组件的子组件索引 1182 1183```ts 1184// xxx.ets 1185@Entry 1186@Component 1187struct ListExample { 1188 private arr: number[] = [] 1189 private scroller: ListScroller = new ListScroller() 1190 @State listSpace: number = 10 1191 @State listChildrenSize: ChildrenMainSize = new ChildrenMainSize(100) 1192 @State listIndex: number = -1 1193 @State mess:string = "null" 1194 @State itemBackgroundColorArr: boolean[] = [false] 1195 aboutToAppear(){ 1196 // 初始化数据源。 1197 for (let i = 0; i < 10; i++) { 1198 this.arr.push(i) 1199 } 1200 this.listChildrenSize.splice(0, 5, [100, 100, 100, 100, 100]) 1201 } 1202 build() { 1203 Column() { 1204 List({ space: this.listSpace, initialIndex: 4, scroller: this.scroller }) { 1205 ForEach(this.arr, (item: number) => { 1206 ListItem() { 1207 Text('item-' + item) 1208 .height( item < 5 ? 100 : this.listChildrenSize.childDefaultSize) 1209 .width('90%') 1210 .fontSize(16) 1211 .textAlign(TextAlign.Center) 1212 .borderRadius(10) 1213 .backgroundColor( this.itemBackgroundColorArr[item] ? 0x68B4FF: 0xFFFFFF) 1214 } 1215 }, (item: string) => item) 1216 } 1217 .backgroundColor(Color.Gray) 1218 .layoutWeight(1) 1219 .scrollBar(BarState.On) 1220 .childrenMainSize(this.listChildrenSize) 1221 .alignListItem(ListItemAlign.Center) 1222 .gesture( 1223 PanGesture() 1224 .onActionUpdate((event: GestureEvent) => { 1225 if (event.fingerList[0] != undefined && event.fingerList[0].localX != undefined && event.fingerList[0].localY != undefined) { 1226 this.listIndex = this.scroller.getItemIndex(event.fingerList[0].localX, event.fingerList[0].localY) 1227 this.itemBackgroundColorArr[this.listIndex] = true; 1228 } 1229 }) 1230 ) 1231 .gesture( 1232 TapGesture({ count: 1 }) 1233 .onAction((event: GestureEvent) => { 1234 if (event) { 1235 this.itemBackgroundColorArr.splice(0,this.itemBackgroundColorArr.length); 1236 } 1237 }) 1238 ) 1239 1240 Text('您当前位置Item索引为：'+ this.listIndex) 1241 .fontColor(Color.Red) 1242 .height(50) 1243 } 1244 } 1245} 1246``` 1247 1248 1249 1250### 示例7（设置边缘渐隐） 1251该示例实现了Scroll组件开启边缘渐隐效果并设置边缘渐隐长度 1252 1253```ts 1254// xxx.ets 1255import { LengthMetrics } from '@kit.ArkUI' 1256@Entry 1257@Component 1258struct ScrollExample { 1259 scroller: Scroller = new Scroller() 1260 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] 1261 1262 build() { 1263 Stack({ alignContent: Alignment.TopStart }) { 1264 Scroll(this.scroller) { 1265 Column() { 1266 ForEach(this.arr, (item: number) => { 1267 Text(item.toString()) 1268 .width('90%') 1269 .height(150) 1270 .backgroundColor(0xFFFFFF) 1271 .borderRadius(15) 1272 .fontSize(16) 1273 .textAlign(TextAlign.Center) 1274 .margin({ top: 10 }) 1275 }, (item: string) => item) 1276 }.width('100%') 1277 } 1278 .fadingEdge(true,{fadingEdgeLength:LengthMetrics.vp(80)}) 1279 1280 1281 1282 }.width('100%').height('100%').backgroundColor(0xDCDCDC) 1283 } 1284} 1285``` 1286 1287
