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