1# Scroll 2 3<!--Kit: ArkUI--> 4<!--Subsystem: ArkUI--> 5<!--Owner: @shengu_lancer; @yylong--> 6<!--Designer: @yylong--> 7<!--Tester: @liuzhenshuo--> 8<!--Adviser: @HelloCrease--> 9 10可滚动的容器组件，当子组件的布局尺寸超过父组件的尺寸时，内容可以滚动。 11 12> **说明：** 13> - 该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> - 该组件嵌套List子组件滚动时，若List不设置宽高，则默认全部加载，在对性能有要求的场景下建议指定List的宽高，最佳实践请参考[懒加载优化性能-Scroll嵌套List导致按需加载失效](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-lazyforeach-optimization#section6296154115367)。 15> - 该组件滚动的前提是主轴方向大小小于内容大小。 16> - Scroll组件[通用属性clip](ts-universal-attributes-sharp-clipping.md)的默认值为true。 17> - Scroll组件的高度超出屏幕显示范围时，可以通过设置通用属性[layoutWeight](ts-universal-attributes-size.md#layoutweight)让Scroll高度适应主轴的剩余空间。 18> - 手指触摸屏幕时，会停止当前触摸范围内所有滚动组件的滚动动画（[scrollTo](#scrollto)和[scrollToIndex](#scrolltoindex)接口触发的滚动动画除外），包括边缘回弹动画。 19> - 组件内部已绑定手势实现跟手滚动等功能，需要增加自定义手势操作时请参考[手势拦截增强](ts-gesture-blocking-enhancement.md)进行处理。 20 21## 子组件 22 23支持单个子组件。 24 25 26## 接口 27 28Scroll(scroller?: Scroller) 29 30创建Scroll滚动容器。 31 32**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 33 34**系统能力：** SystemCapability.ArkUI.ArkUI.Full 35 36**参数：** 37 38| 参数名 | 类型 | 必填 | 说明 | 39| -------- | -------- | -------- | -------- | 40| scroller | [Scroller](#scroller) | 否 | 可滚动组件的控制器。用于与可滚动组件进行绑定。<br/>**说明：** <br/>不允许和其他滚动类组件，如：[ArcList](ts-container-arclist.md)、[List](ts-container-list.md)、[Grid](ts-container-grid.md)、[Scroll](ts-container-scroll.md)和[WaterFlow](ts-container-waterflow.md)绑定同一个滚动控制对象。 | 41 42## 属性 43 44除支持[通用属性](ts-component-general-attributes.md)和[滚动组件通用属性](ts-container-scrollable-common.md#属性)外，还支持以下属性： 45 46### scrollable 47 48scrollable(value: ScrollDirection) 49 50设置滚动方向。 51 52**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 53 54**系统能力：** SystemCapability.ArkUI.ArkUI.Full 55 56**参数：** 57 58| 参数名 | 类型 | 必填 | 说明 | 59| ------ | ------------------------------------------- | ---- | ----------------------------------------------- | 60| value | [ScrollDirection](#scrolldirection枚举说明) | 是 | 滚动方向。<br/>默认值：ScrollDirection.Vertical | 61 62当滚动方向设置为[ScrollDirection.FREE](#scrolldirection枚举说明)时，Scroll组件仅支持部分能力，见[自由滚动模式下支持的能力](#scrolldirection枚举说明)。 63 64### scrollBar 65 66scrollBar(barState: BarState) 67 68设置滚动条状态。如果容器组件无法滚动，则滚动条不显示。如果容器组件的子组件大小为无穷大，则滚动条不支持拖动和伴随滚动。 69 70从API version 10开始，当滚动组件存在圆角时，为避免滚动条被圆角截断，滚动条会自动计算距顶部和底部的避让距离。 71 72**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 73 74**系统能力：** SystemCapability.ArkUI.ArkUI.Full 75 76**参数：** 77 78| 参数名 | 类型 | 必填 | 说明 | 79| -------- | ----------------------------------------- | ---- | -------------------------------------- | 80| barState | [BarState](ts-appendix-enums.md#barstate) | 是 | 滚动条状态。<br/>默认值：BarState.Auto | 81 82### scrollBarColor 83 84scrollBarColor(color: Color | number | string) 85 86设置滚动条的颜色。 87 88**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 89 90**系统能力：** SystemCapability.ArkUI.ArkUI.Full 91 92**参数：** 93 94| 参数名 | 类型 | 必填 | 说明 | 95| ------ | ------------------------------------------------------------ | ---- | -------------- | 96| color | [Color](ts-appendix-enums.md#color) \| number \| string | 是 | 滚动条的颜色。<br/>默认值：'\#66182431'<br/>number为HEX格式颜色，支持rgb或者argb，示例：0xffffff。string为rgb或者argb格式颜色，示例：'#ffffff'。 | 97 98### scrollBarWidth 99 100scrollBarWidth(value: number | string) 101 102设置滚动条的宽度，不支持百分比设置。宽度设置后，滚动条正常状态和按压状态宽度均为滚动条的宽度值。如果滚动条的宽度超过Scroll组件主轴方向的高度，则滚动条的宽度会变为默认值。 103 104**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 105 106**系统能力：** SystemCapability.ArkUI.ArkUI.Full 107 108**参数：** 109 110| 参数名 | 类型 | 必填 | 说明 | 111| ------ | -------------------------- | ---- | ----------------------------------------- | 112| value | number \| string | 是 | 滚动条的宽度。<br/>默认值：4<br/>单位：vp <br/>取值范围：设置为小于0的值时，按默认值处理。设置为0时，不显示滚动条。| 113 114### scrollSnap<sup>10+</sup> 115 116scrollSnap(value: ScrollSnapOptions) 117 118设置Scroll组件的限位滚动模式。 119 120限位动画期间onWillScroll事件上报的滚动操作来源类型为ScrollSource.FLING。 121 122**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 123 124**系统能力：** SystemCapability.ArkUI.ArkUI.Full 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| ------ | ----------------------------------------- | ---- | -------------------------- | 130| value | [ScrollSnapOptions](#scrollsnapoptions10对象说明) | 是 | Scroll组件的限位滚动模式。 | 131 132### edgeEffect 133 134edgeEffect(edgeEffect: EdgeEffect, options?: EdgeEffectOptions) 135 136设置边缘滑动效果。 137 138**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 139 140**系统能力：** SystemCapability.ArkUI.ArkUI.Full 141 142**参数：** 143 144| 参数名 | 类型 | 必填 | 说明 | 145| --------------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | 146| edgeEffect | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | 是 | Scroll组件的边缘滑动效果，支持弹簧效果和阴影效果。<br/>默认值：EdgeEffect.None | 147| options<sup>11+</sup> | [EdgeEffectOptions](ts-container-scrollable-common.md#edgeeffectoptions11对象说明) | 否 | 组件内容大小小于组件自身时，是否开启滑动效果。设置为{ alwaysEnabled: true }会开启滑动效果，{ alwaysEnabled: false }不开启。<br/>默认值：{ alwaysEnabled: true } | 148 149### enableScrollInteraction<sup>10+</sup> 150 151enableScrollInteraction(value: boolean) 152 153设置是否支持滚动手势。 154 155**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 156 157**系统能力：** SystemCapability.ArkUI.ArkUI.Full 158 159**参数：** 160 161| 参数名 | 类型 | 必填 | 说明 | 162| ------ | ------- | ---- | ----------------------------------- | 163| value | boolean | 是 | 是否支持滚动手势。设置为true时可以通过手指或者鼠标滚动，设置为false时无法通过手指或者鼠标滚动，但不影响控制器[Scroller](ts-container-scroll.md#scroller)的滚动接口。<br/>默认值：true | 164 165> **说明：** 166> 167> 组件无法通过鼠标按下拖动操作进行滚动。 168 169### nestedScroll<sup>10+</sup> 170 171nestedScroll(value: NestedScrollOptions) 172 173设置前后两个方向的嵌套滚动模式，实现与父组件的滚动联动。 174 175**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 176 177**系统能力：** SystemCapability.ArkUI.ArkUI.Full 178 179**参数：** 180 181| 参数名 | 类型 | 必填 | 说明 | 182| ------ | ----------------------------------------------------- | ---- | -------------- | 183| value | [NestedScrollOptions](ts-container-scrollable-common.md#nestedscrolloptions10对象说明) | 是 | 嵌套滚动选项。<br/>默认值：{ scrollForward: NestedScrollMode.SELF_ONLY, scrollBackward: NestedScrollMode.SELF_ONLY }<br/>Scroll设置[enablePaging](#enablepaging11)或者[scrollSnap](#scrollsnap10)，并同时设置父组件优先的嵌套滚动时，嵌套滚动不生效。| 184 185### friction<sup>10+</sup> 186 187friction(value: number | Resource) 188 189设置摩擦系数，手动划动滚动区域时生效，仅影响惯性滚动过程，对惯性滚动过程中的链式效果有间接影响。 190 191**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 192 193**系统能力：** SystemCapability.ArkUI.ArkUI.Full 194 195**参数：** 196 197| 参数名 | 类型 | 必填 | 说明 | 198| ------ | ---------------------------------------------------- | ---- | --------------------------------------------------------- | 199| value | number \| [Resource](ts-types.md#resource) | 是 | 摩擦系数。<br/>默认值：非可穿戴设备为0.6，可穿戴设备为0.9。<br/>从API version 11开始，非可穿戴设备默认值为0.7。<br/>从API version 12开始，非可穿戴设备默认值为0.75。<br/>取值范围：(0, +∞)，设置为小于等于0的值时，按默认值处理。 | 200 201### enablePaging<sup>11+</sup> 202 203enablePaging(value: boolean) 204 205设置是否支持划动翻页。如果同时设置了划动翻页enablePaging和限位滚动scrollSnap，则scrollSnap优先生效，enablePaging不生效。 206 207**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 208 209**系统能力：** SystemCapability.ArkUI.ArkUI.Full 210 211**参数：** 212 213| 参数名 | 类型 | 必填 | 说明 | 214| ------ | ------- | ---- | ------------------------------------- | 215| value | boolean | 是 | 是否支持划动翻页。设置为true支持滑动翻页，false不支持。 <br/>默认值：false | 216 217### initialOffset<sup>12+</sup> 218 219initialOffset(value: OffsetOptions) 220 221设置初始滚动偏移量。只在首次布局时生效，后续动态修改该属性值不生效。 222 223**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 224 225**系统能力：** SystemCapability.ArkUI.ArkUI.Full 226 227**参数：** 228 229| 参数名 | 类型 | 必填 | 说明 | 230| ------ | ------- | ---- | ------------------------------------- | 231| value | [OffsetOptions](#offsetoptions12对象说明) | 是 |当输入的大小为百分比时，初始滚动偏移量为Scroll组件主轴方向大小与百分比数值之积。| 232 233### maxZoomScale<sup>20+</sup> 234 235maxZoomScale(scale: number) 236 237设置Scroll组件内容的最大手势缩放比例。 238 239**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 240 241**系统能力：** SystemCapability.ArkUI.ArkUI.Full 242 243**参数：** 244 245| 参数名 | 类型 | 必填 | 说明 | 246| ------ | ------- | ---- | ------------------------------------- | 247| scale | number | 是 |Scroll组件内容的最大手势缩放比例。<br>默认值：1<br>取值范围：(0, +∞)，小于或等于0时按默认值1处理。| 248 249### minZoomScale<sup>20+</sup> 250 251minZoomScale(scale: number) 252 253设置Scroll组件内容的最小手势缩放比例。 254 255**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 256 257**系统能力：** SystemCapability.ArkUI.ArkUI.Full 258 259**参数：** 260 261| 参数名 | 类型 | 必填 | 说明 | 262| ------ | ------- | ---- | ------------------------------------- | 263| scale | number | 是 |Scroll组件内容的最小手势缩放比例。<br>默认值：1<br>取值范围：(0, maxZoomScale]，小于或等于0时按默认值1处理，大于maxZoomScale时按maxZoomScale处理。| 264 265> **说明：** 266> 267> 当maxZoomScale和minZoomScale不同时为1时，Scroll组件会启用缩放手势。 268 269### zoomScale<sup>20+</sup> 270 271zoomScale(scale: number) 272 273设置Scroll组件内容的缩放比例。 274 275**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 276 277**系统能力：** SystemCapability.ArkUI.ArkUI.Full 278 279**参数：** 280 281| 参数名 | 类型 | 必填 | 说明 | 282| ------ | ------- | ---- | ------------------------------------- | 283| scale | number | 是 |设置Scroll组件内容的缩放比例，该参数支持[!!](../../../ui/state-management/arkts-new-binding.md)双向绑定变量。<br>默认值：1<br>取值范围：(0, +∞)，小于或等于0时按默认值1处理。| 284 285### enableBouncesZoom<sup>20+</sup> 286 287enableBouncesZoom(enable: boolean) 288 289启用过缩放回弹效果。 290 291**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 292 293**系统能力：** SystemCapability.ArkUI.ArkUI.Full 294 295**参数：** 296 297| 参数名 | 类型 | 必填 | 说明 | 298| ------ | ------- | ---- | ------------------------------------- | 299| enable | boolean | 是 |启用过缩放回弹效果。设置为true表示启用该效果，设置为false表示禁用该效果。<br>默认值：true | 300 301## ScrollDirection枚举说明 302 303滚动方向枚举。 304 305**系统能力：** SystemCapability.ArkUI.ArkUI.Full 306 307| 名称 | 值 | 说明 | 308| ---------- | -- | ------------------------ | 309| Vertical | 0 | 仅支持竖直方向滚动。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 310| Horizontal | 1 | 仅支持水平方向滚动。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 311| Free<sup>(deprecated) </sup> | 2 | 支持竖直或水平方向滚动。<br/> 从API version 9开始废弃，从API version 20开始推荐使用FREE。| 312| None | 3 | 不可滚动。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 313| FREE<sup>20+</sup> | 4 | 自由滚动。<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。| 314 315FREE（自由滚动）模式下支持的能力： 316 317| **支持的属性** | **支持的事件** | **支持的[Scroller](#scroller)接口** | 318| :--- | :--- | :--- | 319| [scrollBar](#scrollbar) | [onWillScroll](#onwillscroll12) | [scrollTo](#scrollto) | 320| [scrollBarColor](#scrollbarcolor) | [onDidScroll](#ondidscroll12) | [scrollEdge](#scrolledge) | 321| [scrollBarWidth](#scrollbarwidth) | [onScrollEdge](#onscrolledge) | [scrollPage](#scrollpage9) | 322| [scrollBarMargin](./ts-container-scrollable-common.md#scrollbarmargin20) | [onScrollStart](#onscrollstart9) | [currentOffset](#currentoffset) | 323| [edgeEffect](#edgeeffect) | [onScrollStop](#onscrollstop9) | [scrollBy](#scrollby9) | 324| [enableScrollInteraction](#enablescrollinteraction10) | - | [getItemRect](#getitemrect11) | 325| [friction](#friction10) | - | - | 326| [clipContent](./ts-container-scrollable-common.md#clipcontent14) | - | - | 327| [initialOffset](#initialoffset12) | - | - | 328| [scrollable](#scrollable) | - | - | 329 330> **说明:** 331> - `edgeEffect`属性仅支持`Spring`和`None`边缘滑动效果。 332> - `onWillScroll`回调仅支持在跟手滑动阶段重载偏移量。 333> - `onScrollEdge`回调只在到达边缘时触发一次，回弹后不会重复触发。 334> - 在抛滑动画过程中切换边缘模式不会打断动画。 335 336## ScrollSnapOptions<sup>10+</sup>对象说明 337 338限位滚动模式对象。 339 340**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 341 342**系统能力：** SystemCapability.ArkUI.ArkUI.Full 343 344| 名称 | 类型 | 只读 | 可选 | 说明 | 345| ---------- | --------------------|-------------------- | -- | -------- | 346| snapAlign | [ScrollSnapAlign](ts-container-list.md#scrollsnapalign10枚举说明) | 否 | 否 | 设置Scroll组件限位滚动时的对齐方式。<br/>**说明：** <br/>1.该属性默认值为ScrollSnapAlign.NONE。 | 347| snapPagination | [Dimension](ts-types.md#dimension10) \| Array\<Dimension\> | 否 | 是 | 设置Scroll组件限位滚动时的分页点。<br/>**说明：** <br/>1.当属性为Dimension时，Dimension表示每页的大小，系统按照该大小进行分页。<br/>2.当属性为Array\<Dimension\>时，每个Dimension表示分页点，系统按照分页点进行分页。每个Dimension的范围为[0,可滑动距离]。<br/>3.当该属性不填或者Dimension为小于等于0的输入时，按异常值，无限位滚动处理。当该属性值为Array\<Dimension\>数组时，数组中的数值必须为单调递增。<br/>4.当输入为百分比时，实际的大小为Scroll组件的视口与百分比数值之积。 | 348| enableSnapToStart | boolean | 否 | 是 | 在Scroll组件限位滚动模式下，该属性设置为true后，不允许Scroll在开头和第一页间自由滑动，该属性设置为false后，允许Scroll在开头和第一页间自由滑动。<br/>**说明：** <br/>1.该属性值默认为true。<br/>2.该属性仅当snapPagination属性为Array\<Dimension\>时生效，不支持Dimension。 | 349| enableSnapToEnd | boolean | 否 | 是 | 在Scroll组件限位滚动模式下，该属性设置为true后，不允许Scroll在最后一页和末尾间自由滑动，该属性设置为false后，允许Scroll在最后一页和末尾间自由滑动。<br/>**说明：** <br/>1.该属性值默认为true。<br/>2.该属性仅当snapPagination属性为Array\<Dimension\>时生效，不支持Dimension。 | 350 351## 事件 352 353除支持[通用事件](ts-component-general-events.md)和[滚动组件通用事件](ts-container-scrollable-common.md#事件)外，还支持以下事件： 354> **说明：** 355> 356> 不支持滚动组件通用事件中的[onWillScroll](ts-container-scrollable-common.md#onwillscroll12)、[onDidScroll](ts-container-scrollable-common.md#ondidscroll12)事件。 357 358### onScrollFrameBegin<sup>9+</sup> 359 360onScrollFrameBegin(event: OnScrollFrameBeginCallback) 361 362该接口回调时，事件参数传入即将发生的滚动量，事件处理函数中可根据应用场景计算实际需要的滚动量并作为事件处理函数的返回值返回，Scroll将按照返回值的实际滚动量进行滚动。 363 364支持offsetRemain为负值。 365 366若通过onScrollFrameBegin事件和scrollBy方法实现容器嵌套滚动，需设置子滚动节点的EdgeEffect为None。如Scroll嵌套List滚动时，List组件的edgeEffect属性需设置为EdgeEffect.None。 367 368满足以下任一条件时触发该事件： 369 3701. 用户交互（如手指滑动、键鼠操作等）触发滚动。 3712. Scroll惯性滚动。 3723. 调用[fling](#fling12)接口触发滚动。 373 374不触发该事件的条件： 375 3761. 调用除[fling](#fling12)接口外的其他滚动控制接口。 3772. 越界回弹。 3783. 拖动滚动条。 379 380**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 381 382**系统能力：** SystemCapability.ArkUI.ArkUI.Full 383 384**参数：** 385 386| 参数名 | 类型 | 必填 | 说明 | 387| ------ | --------------------------------- | ---- | ------------------ | 388| event | [OnScrollFrameBeginCallback](#onscrollframebegincallback18) | 是 | 每帧滚动开始回调函数。 | 389 390### onScroll<sup>(deprecated)</sup> 391 392onScroll(event: (xOffset: number, yOffset: number) => void) 393 394滚动事件回调，返回滚动时水平、竖直方向偏移量，单位vp。 395 396触发该事件的条件： 397 3981、滚动组件触发滚动时触发，支持键鼠操作等其他触发滚动的输入设置。 399 4002、通过滚动控制器API接口调用。 401 4023、越界回弹。 403 404从API version 12开始废弃不再使用，推荐使用[onWillScroll](#onwillscroll12)事件替代。 405 406**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 407 408**系统能力：** SystemCapability.ArkUI.ArkUI.Full 409 410**参数：** 411 412| 参数名 | 类型 | 必填 | 说明 | 413| ------- | --------------------------------------------------------- | ---- | ---------------------- | 414| xOffset | number | 是 | 每帧滚动时水平方向的偏移量，Scroll的内容向左滚动时偏移量为正，向右滚动时偏移量为负。<br/>单位vp。 | 415| yOffset | number | 是 | 每帧滚动时竖直方向的偏移量，Scroll的内容向上滚动时偏移量为正，向下滚动时偏移量为负。<br/>单位vp。 | 416 417### onWillScroll<sup>12+</sup> 418 419onWillScroll(handler: ScrollOnWillScrollCallback) 420 421滚动事件回调，Scroll滚动前触发。 422 423回调当前帧将要滚动的偏移量和当前滚动状态和滚动操作来源，其中回调的偏移量为计算得到的将要滚动的偏移量值，并非最终实际滚动偏移。可以通过该回调返回值指定Scroll将要滚动的偏移。 424 425触发该事件的条件： 426 4271、滚动组件触发滚动时触发，支持键鼠操作等其他触发滚动的输入设置。 428 4292、通过滚动控制器API接口调用。 430 4313、越界回弹。 432 433> **说明：** 434> 435> 滚动事件的回调函数在滚动过程中会被频繁触发，因此应避免在该回调函数中执行耗时操作，以防止应用出现卡顿和丢帧的问题。最佳实践请参考[主线程耗时操作优化指导-高频回调场景](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-time-optimization-of-the-main-thread#section10112623611)。 436 437**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 438 439**系统能力：** SystemCapability.ArkUI.ArkUI.Full 440 441**参数：** 442 443| 参数名 | 类型 | 必填 | 说明 | 444| ------- | --------------------------------------------------------- | ---- | ---------------------- | 445| handler | [ScrollOnWillScrollCallback](#scrollonwillscrollcallback12) | 是 | Scroll滚动前触发的回调。 | 446 447### onDidScroll<sup>12+</sup> 448 449onDidScroll(handler: ScrollOnScrollCallback) 450 451滚动事件回调，Scroll滚动时触发。 452 453返回当前帧滚动的偏移量和当前滚动状态。 454 455触发该事件的条件： 456 4571、滚动组件触发滚动时触发，支持键鼠操作等其他触发滚动的输入设置。 458 4592、通过滚动控制器API接口调用。 460 4613、越界回弹。 462 463**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 464 465**系统能力：** SystemCapability.ArkUI.ArkUI.Full 466 467**参数：** 468 469| 参数名 | 类型 | 必填 | 说明 | 470| ------- | --------------------------------------------------------- | ---- | ---------------------- | 471| handler | [ScrollOnScrollCallback](#scrollonscrollcallback12) | 是 | Scroll滚动时触发的回调。 | 472 473### onScrollEdge 474 475onScrollEdge(event: OnScrollEdgeCallback) 476 477滚动到边缘事件回调。 478 479触发该事件的条件： 480 4811、滚动组件滚动到边缘时触发，支持键鼠操作等其他触发滚动的输入设置。<br/>2、通过滚动控制器API接口调用。<br/>3、越界回弹。 482 483**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 484 485**系统能力：** SystemCapability.ArkUI.ArkUI.Full 486 487**参数：** 488 489| 参数名 | 类型 | 必填 | 说明 | 490| ------ | --------------------------------- | ---- | ------------------ | 491| event | [OnScrollEdgeCallback](#onscrolledgecallback18) | 是 | 滚动到的边缘位置。<br/>当Scroll设置为水平方向滚动时，上报[Edge.Center](ts-appendix-enums.md#edge)表示水平方向起始位置，上报[Edge.Baseline](ts-appendix-enums.md#edge)表示水平方向末尾位置。由于[Edge.Center](ts-appendix-enums.md#edge)和[Edge.Baseline](ts-appendix-enums.md#edge)枚举值已经废弃，推荐使用[onReachStart](ts-container-scrollable-common.md#onreachstart11)、[onReachEnd](ts-container-scrollable-common.md#onreachend11)事件监听是否滚动到边界。 | 492 493### onScrollEnd<sup>(deprecated) </sup> 494 495onScrollEnd(event: () => void) 496 497滚动停止事件回调。 498 499触发该事件的条件： 500 5011、滚动组件触发滚动后停止，支持键鼠操作等其他触发滚动的输入设置。<br/>2、通过滚动控制器API接口调用后停止，带过渡动效。 502 503该事件从API version 9开始废弃，使用[onScrollStop](#onscrollstop9)事件替代。 504 505**系统能力：** SystemCapability.ArkUI.ArkUI.Full 506 507**参数：** 508 509| 参数名 | 类型 | 必填 | 说明 | 510| ------ | --------------------------------- | ---- | ------------------ | 511| event | () => void | 是 | 滚动停止事件回调。 | 512 513### onScrollStart<sup>9+</sup> 514 515onScrollStart(event: VoidCallback) 516 517滚动开始时触发。手指拖动Scroll或拖动Scroll的滚动条触发的滚动开始时，会触发该事件。使用[Scroller](#scroller)滚动控制器触发的带动画的滚动，动画开始时会触发该事件。 518 519触发该事件的条件： 520 5211、滚动组件开始滚动时触发，支持键鼠操作等其他触发滚动的输入设置。<br/>2、通过滚动控制器API接口调用后开始，带过渡动效。 522 523**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 524 525**系统能力：** SystemCapability.ArkUI.ArkUI.Full 526 527**参数：** 528 529| 参数名 | 类型 | 必填 | 说明 | 530| ------ | --------------------------------- | ---- | ------------------ | 531| event | [VoidCallback](ts-types.md#voidcallback12) | 是 | 滚动开始回调。 | 532 533### onScrollStop<sup>9+</sup> 534 535onScrollStop(event: VoidCallback) 536 537滚动停止时触发。手拖动Scroll或拖动Scroll的滚动条触发的滚动，手离开屏幕后滚动停止时会触发该事件。使用[Scroller](#scroller)滚动控制器触发的带动画的滚动，动画停止时会触发该事件。 538 539触发该事件的条件： 540 5411、滚动组件触发滚动后停止，支持键鼠操作等其他触发滚动的输入设置。<br/>2、通过滚动控制器API接口调用后开始，带过渡动效。 542 543**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 544 545**系统能力：** SystemCapability.ArkUI.ArkUI.Full 546 547**参数：** 548 549| 参数名 | 类型 | 必填 | 说明 | 550| ------ | --------------------------------- | ---- | ------------------ | 551| event | [VoidCallback](ts-types.md#voidcallback12) | 是 | 滚动停止回调。 | 552 553### onDidZoom<sup>20+</sup> 554 555onDidZoom(event: ScrollOnDidZoomCallback) 556 557每帧缩放完成时触发。 558 559**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 560 561**系统能力：** SystemCapability.ArkUI.ArkUI.Full 562 563**参数：** 564 565| 参数名 | 类型 | 必填 | 说明 | 566| ------ | --------------------------------- | ---- | ------------------ | 567| event | [ScrollOnDidZoomCallback](#scrollondidzoomcallback20) | 是 | 每帧缩放完成时回调。 | 568 569### onZoomStart<sup>20+</sup> 570 571onZoomStart(event: VoidCallback) 572 573手势缩放开始触发。 574 575**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 576 577**系统能力：** SystemCapability.ArkUI.ArkUI.Full 578 579**参数：** 580 581| 参数名 | 类型 | 必填 | 说明 | 582| ------ | --------------------------------- | ---- | ------------------ | 583| event | [VoidCallback](ts-types.md#voidcallback12) | 是 | 缩放开始回调。 | 584 585### onZoomStop<sup>20+</sup> 586 587onZoomStop(event: VoidCallback) 588 589手势缩放停止时触发。 590 591**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 592 593**系统能力：** SystemCapability.ArkUI.ArkUI.Full 594 595**参数：** 596 597| 参数名 | 类型 | 必填 | 说明 | 598| ------ | --------------------------------- | ---- | ------------------ | 599| event | [VoidCallback](ts-types.md#voidcallback12) | 是 | 缩放停止回调。 | 600 601## ScrollOnScrollCallback<sup>12+</sup> 602 603type ScrollOnScrollCallback = (xOffset: number, yOffset: number, scrollState: ScrollState) => void 604 605Scroll滚动时触发的回调。 606 607**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 608 609**系统能力：** SystemCapability.ArkUI.ArkUI.Full 610 611**参数：** 612 613| 参数名 | 类型 | 必填 | 说明 | 614| ----------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 615| xOffset | number | 是 | 每帧滚动时水平方向的偏移量，Scroll中的内容向左滚动时偏移量为正，向右滚动时偏移量为负。<br/>单位vp。 | 616| yOffset | number | 是 | 每帧滚动时竖直方向的偏移量，Scroll中的内容向上滚动时偏移量为正，向下滚动时偏移量为负。<br/>单位vp。 | 617| scrollState | [ScrollState](ts-container-list.md#scrollstate枚举说明) | 是 | 当前滚动状态。 | 618 619> **说明：** 620> 621> 若通过onScrollFrameBegin事件和scrollBy方法实现容器嵌套滚动，需设置子滚动节点的EdgeEffect为None。如Scroll嵌套List滚动时，List组件的edgeEffect属性需设置为EdgeEffect.None。 622 623## ScrollOnWillScrollCallback<sup>12+</sup> 624 625type ScrollOnWillScrollCallback = (xOffset: number, yOffset: number, scrollState: ScrollState, scrollSource: ScrollSource) => void | OffsetResult 626 627Scroll滚动前触发的回调。 628 629**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 630 631**系统能力：** SystemCapability.ArkUI.ArkUI.Full 632 633**参数：** 634 635| 参数名 | 类型 | 必填 | 说明 | 636| ----------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 637| xOffset | number | 是 | 每帧滚动时水平方向的偏移量，Scroll中的内容向左滚动时偏移量为正，向右滚动时偏移量为负。<br/>单位vp。 | 638| yOffset | number | 是 | 每帧滚动时竖直方向的偏移量，Scroll中的内容向上滚动时偏移量为正，向下滚动时偏移量为负。<br/>单位vp。 | 639| scrollState | [ScrollState](ts-container-list.md#scrollstate枚举说明) | 是 | 当前滚动状态。 | 640| scrollSource | [ScrollSource](ts-appendix-enums.md#scrollsource12) | 是 | 当前滚动操作的来源。 | 641 642**返回值：** 643 644| 类型 | 说明 | 645| ------------------------------------------------------------ | ------------------------------------------------------------ | 646| void \| [OffsetResult](#offsetresult11对象说明) | 返回OffsetResult时按照开发者指定的偏移量滚动；不返回时按回调参数(xOffset, yOffset)滚动。 | 647 648## OnScrollEdgeCallback<sup>18+</sup> 649 650type OnScrollEdgeCallback = (side: Edge) => void 651 652滚动到边缘时触发的回调。 653 654**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 655 656**系统能力：** SystemCapability.ArkUI.ArkUI.Full 657 658**参数：** 659 660| 参数名 | 类型 | 必填 | 说明 | 661| ------- | ----- | ---- | ------ | 662| side | [Edge](ts-appendix-enums.md#edge) | 是 | 滚动到的边缘位置。 | 663 664## OnScrollFrameBeginCallback<sup>18+</sup> 665 666type OnScrollFrameBeginCallback = (offset: number, state: ScrollState) => OnScrollFrameBeginHandlerResult; 667 668Scroll每帧滚动前触发的回调。 669 670**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 671 672**系统能力：** SystemCapability.ArkUI.ArkUI.Full 673 674**参数：** 675 676| 参数名 | 类型 | 必填 | 说明 | 677| ------ | ------------------------------------------------------- | ---- | -------------------------- | 678| offset | number | 是 | 即将发生的滑动量，单位vp。 | 679| state | [ScrollState](ts-container-list.md#scrollstate枚举说明) | 是 | 当前滑动状态。 | 680 681**返回值：** 682 683| 类型 | 说明 | 684| ------------------------ | -------------------- | 685| [OnScrollFrameBeginHandlerResult](#onscrollframebeginhandlerresult18对象说明) | 返回实际滑动量。 | 686 687## OnScrollFrameBeginHandlerResult<sup>18+</sup>对象说明 688 689[OnScrollFrameBeginCallback](#onscrollframebegincallback18)返回的实际滚动偏移量。 690 691> **说明：** 692> 693> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 694 695**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 696 697**系统能力：** SystemCapability.ArkUI.ArkUI.Full 698 699| 名称 | 类型 | 只读 | 可选 | 说明 | 700| ----- | ------ | ---- | -- | ----- | 701| offsetRemain<sup>9+</sup> | number | 否 | 否 | 实际滚动偏移量。<br/>单位vp。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 702 703## ScrollOnDidZoomCallback<sup>20+</sup> 704 705type ScrollOnDidZoomCallback = (scale: number) => void 706 707Scroll每帧缩放完成时触发的回调。 708 709**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 710 711**系统能力：** SystemCapability.ArkUI.ArkUI.Full 712 713**参数：** 714 715| 参数名 | 类型 | 必填 | 说明 | 716| ----------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 717| scale | number | 是 | 当前缩放倍数。 | 718 719 720## Scroller 721 722可滚动容器组件的控制器，可以将此组件绑定至容器组件，然后通过它控制容器组件的滚动。同一个控制器不可以控制多个容器组件，目前支持绑定到ArcList、ArcScrollBar、List、Scroll、ScrollBar、Grid、WaterFlow上。 723 724>**说明：** 725> 726>1、Scroller控制器与滚动容器组件的绑定发生在组件创建阶段。<br/> 727>2、Scroller控制器与滚动容器组件绑定后才可以正常调用Scroller方法，否则根据调用接口不同会不生效或者抛异常。<br/> 728>3、以[aboutToAppear](ts-custom-component-lifecycle.md#abouttoappear)为例，aboutToAppear在创建自定义组件的新实例后，在执行其build()方法之前执行。因此如果滚动组件在自定义组件build内，在该自定义组件aboutToAppear执行时，内部滚动组件还没有创建，是不能正常调用上述Scroller方法的。<br/> 729>4、以[onAppear](ts-universal-events-show-hide.md#onappear)为例，组件挂载显示后触发此回调。因此在滚动组件的onAppear回调执行时，滚动组件已经创建并已经和Scroller绑定成功，是可以正常调用Scroller方法的。 730 731### 导入对象 732 733``` 734scroller: Scroller = new Scroller(); 735``` 736 737### constructor 738 739constructor() 740 741Scroller的构造函数。 742 743**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 744 745**系统能力：** SystemCapability.ArkUI.ArkUI.Full 746 747### scrollTo 748 749scrollTo(options: ScrollOptions) 750 751 752滑动到指定位置。 753 754**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 755 756**系统能力：** SystemCapability.ArkUI.ArkUI.Full 757 758**参数：** 759 760| 参数名 | 类型 | 必填 | 说明 | 761| ----- | ---- | ---- | --------- | 762| options | [ScrollOptions](#scrolloptions18对象说明) | 是 | 滑动到指定位置的参数。 763 764> **说明：** 765> 766> ScrollTo动画速度大于200vp/s时，滚动组件区域内的组件不响应点击事件。 767> 768 769### scrollEdge 770 771scrollEdge(value: Edge, options?: ScrollEdgeOptions) 772 773滚动到容器边缘，不区分滚动轴方向，Edge.Top和Edge.Start表现相同，Edge.Bottom和Edge.End表现相同。 774Scroll组件默认有动画，Grid、List、WaterFlow组件默认无动画。 775 776**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 777 778**系统能力：** SystemCapability.ArkUI.ArkUI.Full 779 780**参数：** 781 782| 参数名 | 类型 | 必填 | 说明 | 783| ----- | ---- | ---- | --------- | 784| value | [Edge](ts-appendix-enums.md#edge) | 是 | 滚动到的边缘位置。| 785| options<sup>12+</sup> | [ScrollEdgeOptions](#scrolledgeoptions12对象说明) | 否 | 设置滚动到边缘位置的模式。 | 786 787### fling<sup>12+</sup> 788 789fling(velocity: number): void 790 791 792滚动类组件根据传入的初始速度进行惯性滚动。 793 794**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 795 796**系统能力：** SystemCapability.ArkUI.ArkUI.Full 797 798**参数：** 799 800| 参数名 | 类型 | 必填 | 说明 | 801| -------- | -------- | ---- | ------------------------------------------------------------ | 802| velocity | number | 是 | 惯性滚动的初始速度值。单位：vp/s<br/>**说明：**<br/>velocity值设置为0，视为异常值，本次滚动不生效。如果值为正数，则向顶部滚动；如果值为负数，则向底部滚动。 <br/>取值范围：(-∞, +∞)| 803 804**错误码**： 805 806以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)和[滚动类组件错误码](../errorcode-scroll.md)。 807 808| 错误码ID | 错误信息 | 809| ------- | -------- | 810| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 811| 100004 | Controller not bound to component. | 812 813### scrollPage<sup>9+</sup> 814 815scrollPage(value: ScrollPageOptions) 816 817滚动到下一页或者上一页。 818 819**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 820 821**系统能力：** SystemCapability.ArkUI.ArkUI.Full 822 823**参数：** 824 825| 参数名 | 类型 | 必填 | 说明 | 826| ------ | -------------------------------------------------- | ---- | -------------- | 827| value | [ScrollPageOptions](#scrollpageoptions14对象说明) | 是 | 设置翻页模式。 | 828 829### scrollPage<sup>(deprecated)</sup> 830 831scrollPage(value: { next: boolean, direction?: Axis }) 832 833滚动到下一页或者上一页。从API version 9开始，该接口不再维护，推荐使用[scrollPage<sup>9+</sup>](#scrollpage9)。 834 835**系统能力：** SystemCapability.ArkUI.ArkUI.Full 836 837**参数：** 838 839| 参数名 | 类型 | 必填 | 说明 | 840| --------- | ------- | ---- | ------------------------------ | 841| next | boolean | 是 | 是否向下翻页。true表示向下翻页，false表示向上翻页。 | 842| direction | [Axis](ts-appendix-enums.md#axis) | 否 | 设置滚动方向为水平或竖直方向。 | 843 844### currentOffset 845 846currentOffset(): OffsetResult 847 848获取当前的滚动偏移量。 849 850**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 851 852**系统能力：** SystemCapability.ArkUI.ArkUI.Full 853 854**返回值：** 855 856| 类型 | 说明 | 857| -------- | -------- | 858| [OffsetResult<sup>11+</sup>](#offsetresult11对象说明) | 返回当前的滚动偏移量。<br/>**说明：**<br/>当scroller控制器未绑定容器组件或者容器组件被异常释放时，currentOffset的返回值为空。| 859 860### scrollToIndex 861 862scrollToIndex(value: number, smooth?: boolean, align?: ScrollAlign, options?: ScrollToIndexOptions) 863 864滑动到指定Index，支持设置滑动额外偏移量。 865 866开启smooth动效时，会对经过的所有item进行加载和布局计算，当大量加载item时会导致性能问题，建议先调用scrollToIndex不带动画跳转到目标附近位置，再调用scrollToIndex带动画滚动到目标位置。 867 868 869> **说明：** 870> 871> 1.仅支持ArcList、Grid、List、WaterFlow组件。 872> 873> 2.在LazyForEach、ForEach、Repeat刷新数据源时，需确保在数据刷新完成之后再调用此接口。 874 875**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 876 877**系统能力：** SystemCapability.ArkUI.ArkUI.Full 878 879**参数：** 880 881| 参数名 | 类型 | 必填 | 说明 | 882| --------------------- | -------- | ---- | ------------------------------------------------------------ | 883| value | number | 是 | 要滑动到的目标元素在当前容器中的索引值。 <br/>**说明：** <br/>value值设置成负值或者大于当前容器子组件的最大索引值，视为异常值，本次跳转不生效。 | 884| smooth | boolean | 否 | 设置滑动到列表项在列表中的索引值时是否有动效，true表示有动效，false表示没有动效。<br/>默认值：false。| 885| align | [ScrollAlign](#scrollalign10枚举说明) | 否 | 指定滑动到的元素与当前容器的对齐方式。<br/>List中的默认值为：ScrollAlign.START。Grid中默认值为：ScrollAlign.AUTO。WaterFlow中的默认值为：ScrollAlign.START。<br/>**说明：** <br/>仅List、Grid、WaterFlow组件支持该参数。 | 886| options<sup>12+</sup> | [ScrollToIndexOptions](#scrolltoindexoptions12对象说明) | 否 | 设置滑动到指定Index的选项，如额外偏移量。<br/>默认值：0，单位：vp。 | 887 888### scrollBy<sup>9+</sup> 889 890scrollBy(dx: Length, dy: Length) 891 892 893滑动指定距离。 894 895 896> **说明：** 897> 898> 支持ArcList、Scroll、List、Grid、WaterFlow组件。 899 900**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 901 902**系统能力：** SystemCapability.ArkUI.ArkUI.Full 903 904**参数：** 905 906| 参数名 | 类型 | 必填 | 说明 | 907| ----- | ------ | ---- | ----------------- | 908| dx | [Length](ts-types.md#length) | 是 | 水平方向滚动距离，不支持百分比形式。 <br/>取值范围：(-∞, +∞) | 909| dy | [Length](ts-types.md#length) | 是 | 竖直方向滚动距离，不支持百分比形式。 <br/>取值范围：(-∞, +∞) | 910 911### isAtEnd<sup>10+</sup> 912 913isAtEnd(): boolean 914 915查询组件是否滚动到底部。 916 917> **说明：** 918> 919> 支持ArcList、Scroll、List、Grid、WaterFlow组件。 920 921**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 922 923**系统能力：** SystemCapability.ArkUI.ArkUI.Full 924 925**返回值：** 926 927| 类型 | 说明 | 928| ------- | -------- | 929| boolean | true表示组件已经滚动到底部，false表示组件还没滚动到底部。 | 930 931### getItemRect<sup>11+</sup> 932 933getItemRect(index: number): RectResult 934 935获取子组件的大小及相对容器组件的位置。 936 937> **说明：** 938> 939> 支持ArcList、Scroll、List、Grid、WaterFlow组件。 940 941**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 942 943**系统能力：** SystemCapability.ArkUI.ArkUI.Full 944 945**参数：** 946 947| 参数名 | 类型 | 必填 | 说明 | 948| ----- | ------ | ---- | ----------------- | 949| index | number | 是 | 子组件的索引值。 | 950 951> **说明：** 952> 953> - index必须是当前显示区域显示的子组件的索引值，否则视为非法值。 954> - 非法值返回的大小和位置均为0。 955 956**返回值：** 957 958| 类型 | 说明 | 959| ------------------- | -------- | 960| [RectResult](ts-universal-attributes-on-child-touch-test.md#rectresult) | 子组件的大小和相对于组件的位置。<br/>单位：vp。 | 961 962**错误码**： 963 964以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)和[滚动类组件错误码](../errorcode-scroll.md)。 965 966| 错误码ID | 错误信息 | 967| ------- | -------- | 968| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 969| 100004 | Controller not bound to component. | 970### getItemIndex<sup>14+</sup> 971 972getItemIndex(x: number, y: number): number 973 974通过坐标获取子组件的索引。 975 976> **说明：** 977> 978> 支持List、Grid、WaterFlow组件。 979 980**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 981 982**系统能力：** SystemCapability.ArkUI.ArkUI.Full 983 984**参数：** 985 986| 参数名 | 类型 | 必填 | 说明 | 987| ----- | ------ | ---- | ----------------- | 988| x | number | 是 | x轴坐标，单位为vp。 | 989| y | number | 是 | y轴坐标，单位为vp。 | 990 991> **说明：** 992> 993> 非法值返回的索引为-1。 994 995**返回值：** 996 997| 类型 | 说明 | 998| ------------------- | -------- | 999| number | 返回子组件的索引。 | 1000 1001**错误码**： 1002 1003以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)和[滚动类组件错误码](../errorcode-scroll.md)。 1004 1005| 错误码ID | 错误信息 | 1006| ------- | -------- | 1007| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1008| 100004 |The controller not bound to component. | 1009 1010## OffsetResult<sup>11+</sup>对象说明 1011 1012滑动偏移量对象。 1013 1014**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1015 1016**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1017 1018| 名称 | 类型 | 只读 | 可选 | 说明 | 1019| ------- |------- | ---- | ---- | -------------------------------- | 1020| xOffset | number | 否 | 否 | 水平滑动偏移。<br/>返回值单位为vp。 | 1021| yOffset | number | 否 | 否 | 竖直滑动偏移。<br/>返回值单位为vp。 | 1022 1023## ScrollAnimationOptions<sup>12+</sup>对象说明 1024 1025自定义滚动动效的参数选项。 1026 1027**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1028 1029**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1030 1031| 名称 | 类型 | 只读 | 可选 | 说明 | 1032| ----- | ------ | ------ | -- | ----------------- | 1033| duration | number | 否 | 是 | 设置滚动时长。<br/>默认值：1000<br/>**说明：** <br/>设置为小于0的值时，按默认值显示。 | 1034| curve | [Curve](ts-appendix-enums.md#curve) \| [ICurve](../js-apis-curve.md#icurve9) | 否 | 是 | 设置滚动曲线。<br/>默认值：Curve.Ease | 1035| canOverScroll | boolean | 否 | 是 | 设置滚动动画滚动到边界后，是否转换成越界回弹动画。<br/>默认值：false<br/>**说明：** <br/> 仅在设置为true，且组件的edgeEffect设置为[EdgeEffect.Spring](ts-appendix-enums.md#edgeeffect)时，使用动画滚动到边界会转换为越界回弹动画，设置为false时，滚动到边界会直接停止动画，不会转换为越界回弹动画。 <br>从API version 20开始，如果[ScrollOptions](#scrolloptions18对象说明)中的canOverScroll设置为true，表示滚动可以停留在过界位置，滚动动画过界后不会转换为回弹动画。| 1036 1037## ScrollAlign<sup>10+</sup>枚举说明 1038 1039对齐方式枚举。 1040 1041**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1042 1043**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1044 1045| 名称 | 说明 | 1046| ------ | ------------------------------ | 1047| START | 首部对齐。指定item首部与滚动容器组件首部对齐。 | 1048| CENTER | 居中对齐。指定item主轴方向居中对齐于滚动容器组件。 | 1049| END | 尾部对齐。指定item尾部与滚动容器组件尾部对齐。 | 1050| AUTO | 自动对齐。<br/>若指定item完全处于显示区，不做调整。否则依照滑动距离最短的原则，将指定item首部对齐或尾部对齐于滚动容器组件，使指定item完全处于显示区。| 1051 1052## ScrollToIndexOptions<sup>12+</sup>对象说明 1053 1054滑动到指定Index的参数选项。 1055 1056**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1057 1058**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1059 1060| 名称 | 类型 | 只读 | 可选 | 说明 | 1061| ----- | ------ | ------ | -- | ----------------- | 1062| extraOffset | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 否 | 是 | 滑动到指定Index的额外偏移量。如果值为正数，则向底部额外偏移；如果值为负数，则向顶部额外偏移。 | 1063 1064## ScrollPageOptions<sup>14+</sup>对象说明 1065 1066翻页模式的参数选项。 1067 1068**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 1069 1070**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1071 1072| 名称 | 类型 | 只读 | 可选 | 说明 | 1073| --------- | -------- | ---- | -- | ------------------------------------------------------------ | 1074| next | boolean | 否 | 否 | 是否向下翻页。true表示向下翻页，false表示向上翻页。 | 1075| animation | boolean | 否 | 是 | 是否开启翻页动画效果。true有动画，false无动画。<br />默认值：false。 | 1076 1077## OffsetOptions<sup>12+</sup>对象说明 1078 1079初始滚动偏移量的参数选项。 1080 1081**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1082 1083**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1084 1085| 名称 | 类型 | 只读 | 可选 | 说明 | 1086| ----- | ------| ------- | -- | ----------------- | 1087| xOffset | [Dimension](ts-types.md#dimension10) | 否 | 是 |水平滚动偏移。<br/>默认值：0 | 1088| yOffset | [Dimension](ts-types.md#dimension10) | 否 | 是 |垂直滚动偏移。<br/>默认值：0| 1089 1090## ScrollEdgeOptions<sup>12+</sup>对象说明 1091 1092滚动到边缘位置的参数选项。 1093 1094**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1095 1096**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1097 1098| 名称 | 类型 | 只读 | 可选 | 说明 | 1099| --------- | -------- | ---- | -- | ------------------------------------------------------------ | 1100| velocity | number | 否 | 是 | 设置滚动到容器边缘的固定速度。如果设置小于等于0的值，参数不生效。<br/>默认值：0<br/> 单位： vp/s | 1101 1102## ScrollOptions<sup>18+</sup>对象说明 1103 1104滚动到指定位置的参数选项。 1105 1106> **说明：** 1107> 1108> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 1109 1110**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1111 1112**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1113 1114| 名称 | 类型 | 只读 | 可选 | 说明 | 1115| --------- | ------------------------------------------------------------ | ---- | -- | ------------------------------------------------------------ | 1116| xOffset<sup>10+</sup> | number \| string | 否 | 否 | 水平滚动偏移。<br/>**说明：** <br/>该参数值不支持设置百分比。<br/>仅滚动轴为x轴时生效。<br/>取值范围：当值小于0时，不带动画的滚动，按0处理。带动画的滚动，默认滚动到起始位置后停止，可通过设置animation参数，使滚动在越界时启动回弹动画。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 1117| yOffset<sup>10+</sup> | number \| string | 否 | 否 | 垂直滚动偏移。<br/>**说明：** <br/>该参数值不支持设置百分比。<br/>仅滚动轴为y轴时生效。<br/>取值范围：当值小于0时，不带动画的滚动，按0处理。带动画的滚动，默认滚动到起始位置后停止，可通过设置animation参数，使滚动在越界时启动回弹动画。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 1118| animation<sup>10+</sup> | [ScrollAnimationOptions](#scrollanimationoptions12对象说明) \| boolean | 否 | 是 | 动画配置。<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/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1119| canOverScroll<sup>20+</sup> | boolean | 否 | 是 | 滚动目标位置是否可以超出边界停留。仅当组件的edgeEffect设置为EdgeEffect.Spring时，滚动能够越界停留。<br/>设置为true时滚动可以在过界后停留，设置为false时滚动无法在过界后停留。<br/>默认值：false <br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。| 1120 1121## UIScrollEvent<sup>19+</sup> 1122frameNode中[getEvent('Scroll')](../js-apis-arkui-frameNode.md#geteventscroll19)方法的返回值，可用于给Scroll节点设置滚动事件。 1123 1124UIScrollEvent继承于[UIScrollableCommonEvent](./ts-container-scrollable-common.md#uiscrollablecommonevent19)。 1125 1126### setOnWillScroll<sup>19+</sup> 1127 1128setOnWillScroll(callback: ScrollOnWillScrollCallback | undefined): void 1129 1130设置[onWillScroll](#onwillscroll12)事件的回调。 1131 1132方法入参为undefined时，会重置事件回调。 1133 1134**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1135 1136**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1137 1138**参数：** 1139 1140| 参数名 | 类型 | 必填 | 说明 | 1141| ------ | ------ | ---- | -------------------------- | 1142| callback | [ScrollOnWillScrollCallback](./ts-container-scroll.md#scrollonwillscrollcallback12) \| undefined | 是 | onWillScroll事件的回调函数。 | 1143 1144### setOnDidScroll<sup>19+</sup> 1145 1146setOnDidScroll(callback: ScrollOnScrollCallback | undefined): void 1147 1148设置[onDidScroll](#ondidscroll12)事件的回调。 1149 1150方法入参为undefined时，会重置事件回调。 1151 1152**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1153 1154**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1155 1156**参数：** 1157 1158| 参数名 | 类型 | 必填 | 说明 | 1159| ------ | ------ | ---- | -------------------------- | 1160| callback | [ScrollOnScrollCallback](./ts-container-scroll.md#scrollonscrollcallback12) \| undefined | 是 | onDidScroll事件的回调函数。 | 1161 1162## 示例 1163### 示例1（设置scroller控制器） 1164该示例展示了Scroll组件部分属性和scroller控制器的使用。 1165 1166```ts 1167// xxx.ets 1168import { curves } from '@kit.ArkUI'; 1169 1170@Entry 1171@Component 1172struct ScrollExample { 1173 scroller: Scroller = new Scroller(); 1174 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; 1175 1176 build() { 1177 Stack({ alignContent: Alignment.TopStart }) { 1178 Scroll(this.scroller) { 1179 Column() { 1180 ForEach(this.arr, (item: number) => { 1181 Text(item.toString()) 1182 .width('90%') 1183 .height(150) 1184 .backgroundColor(0xFFFFFF) 1185 .borderRadius(15) 1186 .fontSize(16) 1187 .textAlign(TextAlign.Center) 1188 .margin({ top: 10 }) 1189 }, (item: number) => item.toString()) 1190 }.width('100%') 1191 } 1192 .scrollable(ScrollDirection.Vertical) // 滚动方向纵向 1193 .scrollBar(BarState.On) // 滚动条常驻显示 1194 .scrollBarColor(Color.Gray) // 滚动条颜色 1195 .scrollBarWidth(10) // 滚动条宽度 1196 .friction(0.6) 1197 .edgeEffect(EdgeEffect.None) 1198 .onWillScroll((xOffset: number, yOffset: number, scrollState: ScrollState) => { 1199 console.info(xOffset + ' ' + yOffset); 1200 }) 1201 .onScrollEdge((side: Edge) => { 1202 console.info('To the edge'); 1203 }) 1204 .onScrollStop(() => { 1205 console.info('Scroll Stop'); 1206 }) 1207 1208 Button('scroll 150') 1209 .height('5%') 1210 .onClick(() => { // 点击后下滑指定距离150.0vp 1211 this.scroller.scrollBy(0, 150); 1212 }) 1213 .margin({ top: 10, left: 20 }) 1214 Button('scroll 100') 1215 .height('5%') 1216 .onClick(() => { // 点击后滑动到指定位置，即下滑100.0vp的距离 1217 const yOffset: number = this.scroller.currentOffset().yOffset; 1218 this.scroller.scrollTo({ xOffset: 0, yOffset: yOffset + 100 }); 1219 }) 1220 .margin({ top: 60, left: 20 }) 1221 Button('scroll 100') 1222 .height('5%') 1223 .onClick(() => { // 点击后滑动到指定位置，即下滑100.0vp的距离，滑动过程配置有动画 1224 let curve = curves.interpolatingSpring(10, 1, 228, 30); //创建一个弹簧曲线 1225 const yOffset: number = this.scroller.currentOffset().yOffset; 1226 this.scroller.scrollTo({ xOffset: 0, yOffset: yOffset + 100, animation: { duration: 1000, curve: curve } }); 1227 }) 1228 .margin({ top: 110, left: 20 }) 1229 Button('back top') 1230 .height('5%') 1231 .onClick(() => { // 点击后回到顶部 1232 this.scroller.scrollEdge(Edge.Top); 1233 }) 1234 .margin({ top: 160, left: 20 }) 1235 Button('next page') 1236 .height('5%') 1237 .onClick(() => { // 点击后滑到下一页 1238 this.scroller.scrollPage({ next: true ,animation: true }); 1239 }) 1240 .margin({ top: 210, left: 20 }) 1241 Button('fling -3000') 1242 .height('5%') 1243 .onClick(() => { // 点击后触发初始速度为-3000vp/s的惯性滚动 1244 this.scroller.fling(-3000); 1245 }) 1246 .margin({ top: 260, left: 20 }) 1247 Button('scroll to bottom 700') 1248 .height('5%') 1249 .onClick(() => { // 点击后滑到下边缘，速度值是700vp/s 1250 this.scroller.scrollEdge(Edge.Bottom, { velocity: 700 }); 1251 }) 1252 .margin({ top: 310, left: 20 }) 1253 }.width('100%').height('100%').backgroundColor(0xDCDCDC) 1254 } 1255} 1256``` 1257 1258 1259 1260### 示例2（嵌套滚动实现方式一） 1261该示例使用onScrollFrameBegin事件实现了内层List组件和外层Scroll组件的嵌套滚动。 1262```ts 1263import { LengthMetrics } from '@kit.ArkUI'; 1264 1265@Entry 1266@Component 1267struct NestedScroll { 1268 @State listPosition: number = 0; // 0代表滚动到List顶部，1代表中间值，2代表滚动到List底部。 1269 private arr: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; 1270 private scrollerForScroll: Scroller = new Scroller(); 1271 private scrollerForList: Scroller = new Scroller(); 1272 1273 build() { 1274 Flex() { 1275 Scroll(this.scrollerForScroll) { 1276 Column() { 1277 Text("Scroll Area") 1278 .width("100%") 1279 .height("40%") 1280 .backgroundColor(0X330000FF) 1281 .fontSize(16) 1282 .textAlign(TextAlign.Center) 1283 .onClick(() => { 1284 this.scrollerForList.scrollToIndex(5, false, ScrollAlign.START, { extraOffset: LengthMetrics.vp(5) }); 1285 }) 1286 1287 List({ space: 20, scroller: this.scrollerForList }) { 1288 ForEach(this.arr, (item: number) => { 1289 ListItem() { 1290 Text("ListItem" + item) 1291 .width("100%") 1292 .height("100%") 1293 .borderRadius(15) 1294 .fontSize(16) 1295 .textAlign(TextAlign.Center) 1296 .backgroundColor(Color.White) 1297 }.width("100%").height(100) 1298 }, (item: string) => item) 1299 } 1300 .width("100%") 1301 .height("50%") 1302 .edgeEffect(EdgeEffect.None) 1303 .friction(0.6) 1304 .onReachStart(() => { 1305 this.listPosition = 0; 1306 }) 1307 .onReachEnd(() => { 1308 this.listPosition = 2; 1309 }) 1310 .onScrollFrameBegin((offset: number) => { 1311 if ((this.listPosition == 0 && offset <= 0) || (this.listPosition == 2 && offset >= 0)) { 1312 this.scrollerForScroll.scrollBy(0, offset); 1313 return { offsetRemain: 0 }; 1314 } 1315 this.listPosition = 1; 1316 return { offsetRemain: offset }; 1317 }) 1318 1319 Text("Scroll Area") 1320 .width("100%") 1321 .height("40%") 1322 .backgroundColor(0X330000FF) 1323 .fontSize(16) 1324 .textAlign(TextAlign.Center) 1325 } 1326 } 1327 .width("100%").height("100%") 1328 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding(20) 1329 } 1330} 1331``` 1332 1333 1334 1335### 示例3（嵌套滚动实现方式二） 1336该示例使用nestedScroll属性实现了内层List组件和外层Scroll组件的嵌套滚动。 1337```ts 1338@Entry 1339@Component 1340struct StickyNestedScroll { 1341 @State arr: number[] = []; 1342 1343 @Styles 1344 listCard() { 1345 .backgroundColor(Color.White) 1346 .height(72) 1347 .width("100%") 1348 .borderRadius(12) 1349 } 1350 1351 build() { 1352 Scroll() { 1353 Column() { 1354 Text("Scroll Area") 1355 .width("100%") 1356 .height("40%") 1357 .backgroundColor('#0080DC') 1358 .textAlign(TextAlign.Center) 1359 Tabs({ barPosition: BarPosition.Start }) { 1360 TabContent() { 1361 List({ space: 10 }) { 1362 ForEach(this.arr, (item: number) => { 1363 ListItem() { 1364 Text("item" + item) 1365 .fontSize(16) 1366 }.listCard() 1367 }, (item: number) => item.toString()) 1368 }.width("100%") 1369 .edgeEffect(EdgeEffect.Spring) 1370 .nestedScroll({ 1371 scrollForward: NestedScrollMode.PARENT_FIRST, 1372 scrollBackward: NestedScrollMode.SELF_FIRST 1373 }) 1374 }.tabBar("Tab1") 1375 1376 TabContent() { 1377 }.tabBar("Tab2") 1378 } 1379 .vertical(false) 1380 .height("100%") 1381 }.width("100%") 1382 } 1383 .edgeEffect(EdgeEffect.Spring) 1384 .friction(0.6) 1385 .backgroundColor('#DCDCDC') 1386 .scrollBar(BarState.Off) 1387 .width('100%') 1388 .height('100%') 1389 } 1390 1391 aboutToAppear() { 1392 for (let i = 0; i < 30; i++) { 1393 this.arr.push(i); 1394 } 1395 } 1396} 1397``` 1398 1399### 示例4（嵌套滚动父组件向子组件传递滚动） 1400该示例使用enableScrollInteraction属性和onScrollFrameBegin事件实现了父组件向子组件传递滚动。 1401```ts 1402@Entry 1403@Component 1404struct NestedScroll { 1405 private headerHeight: number = 0; 1406 private arr: number[] = []; 1407 private scrollerForParent: Scroller = new Scroller(); 1408 private scrollerForChild: Scroller = new Scroller(); 1409 1410 aboutToAppear(): void { 1411 for (let i = 0; i < 10; i++) { 1412 this.arr.push(i); 1413 } 1414 } 1415 1416 build() { 1417 Scroll(this.scrollerForParent) { 1418 Column() { 1419 Text("Scroll Area") 1420 .width("100%") 1421 .height("40%") 1422 .backgroundColor(0X330000FF) 1423 .fontSize(16) 1424 .textAlign(TextAlign.Center) 1425 .onClick(() => { 1426 this.scrollerForChild.scrollToIndex(5); 1427 }) 1428 .onSizeChange((oldValue: SizeOptions, newValue: SizeOptions) => { 1429 this.headerHeight = newValue.height! as number; 1430 }) 1431 List({ space: 20, scroller: this.scrollerForChild }) { 1432 ForEach(this.arr, (item: number) => { 1433 ListItem() { 1434 Text("ListItem" + item) 1435 .width("100%") 1436 .height("100%") 1437 .borderRadius(15) 1438 .fontSize(16) 1439 .textAlign(TextAlign.Center) 1440 .backgroundColor(Color.White) 1441 }.width("100%").height(100) 1442 }, (item: number) => item.toString()) 1443 } 1444 .width("100%") 1445 .height("100%") 1446 .edgeEffect(EdgeEffect.None) 1447 .scrollBar(BarState.Off) 1448 .enableScrollInteraction(false) 1449 1450 Text("Scroll Area") 1451 .width("100%") 1452 .height("40%") 1453 .backgroundColor(0X330000FF) 1454 .fontSize(16) 1455 .textAlign(TextAlign.Center) 1456 } 1457 } 1458 .scrollBar(BarState.Off) 1459 .edgeEffect(EdgeEffect.Spring) 1460 .onScrollFrameBegin((offset: number, state: ScrollState) => { 1461 let retOffset = offset; 1462 let currOffset = this.scrollerForParent.currentOffset().yOffset; 1463 let newOffset = currOffset + offset; 1464 if (offset > 0) { 1465 if (this.scrollerForChild.isAtEnd()) { 1466 return { offsetRemain: offset }; 1467 } 1468 if (newOffset > this.headerHeight) { 1469 retOffset = this.headerHeight - currOffset; 1470 } 1471 this.scrollerForChild.scrollBy(0, offset - retOffset); 1472 } else { 1473 if (this.scrollerForChild.currentOffset().yOffset <= 0) { 1474 return { offsetRemain: offset }; 1475 } 1476 if (newOffset < this.headerHeight) { 1477 retOffset = this.headerHeight - currOffset; 1478 } 1479 this.scrollerForChild.scrollBy(0, offset - retOffset); 1480 } 1481 return { offsetRemain: retOffset }; 1482 }) 1483 .width("100%") 1484 .height("100%") 1485 .backgroundColor(0xDCDCDC) 1486 } 1487} 1488``` 1489 1490### 示例5（设置限位滚动） 1491该示例实现了Scroll组件的限位滚动。 1492```ts 1493@Entry 1494@Component 1495struct Index { 1496 scroller: Scroller = new Scroller(); 1497 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]; 1498 build() { 1499 Scroll(this.scroller) { 1500 Column() { 1501 ForEach(this.arr, (item: number) => { 1502 Text(item.toString()) 1503 .width('90%') 1504 .height(200) 1505 .backgroundColor(0xFFFFFF) 1506 .borderWidth(1) 1507 .borderColor(Color.Black) 1508 .borderRadius(15) 1509 .fontSize(16) 1510 .textAlign(TextAlign.Center) 1511 }, (item: number) => item.toString()) 1512 }.width('100%').backgroundColor(0xDCDCDC) 1513 } 1514 .backgroundColor(Color.Yellow) 1515 .height('100%') 1516 .edgeEffect(EdgeEffect.Spring) 1517 .scrollSnap({snapAlign:ScrollSnapAlign.START, snapPagination:400, enableSnapToStart:true, enableSnapToEnd:true}) 1518 } 1519} 1520``` 1521 1522 1523### 示例6（获取子组件索引） 1524该示例展示了如何获得List组件的子组件索引。 1525 1526```ts 1527// xxx.ets 1528@Entry 1529@Component 1530struct ListExample { 1531 private arr: number[] = []; 1532 private scroller: ListScroller = new ListScroller(); 1533 @State listSpace: number = 10; 1534 @State listChildrenSize: ChildrenMainSize = new ChildrenMainSize(100); 1535 @State listIndex: number = -1; 1536 @State itemBackgroundColorArr: boolean[] = [false]; 1537 aboutToAppear(){ 1538 // 初始化数据源。 1539 for (let i = 0; i < 10; i++) { 1540 this.arr.push(i); 1541 } 1542 this.listChildrenSize.splice(0, 5, [100, 100, 100, 100, 100]); 1543 } 1544 build() { 1545 Column() { 1546 List({ space: this.listSpace, initialIndex: 4, scroller: this.scroller }) { 1547 ForEach(this.arr, (item: number) => { 1548 ListItem() { 1549 Text('item-' + item) 1550 .height( item < 5 ? 100 : this.listChildrenSize.childDefaultSize) 1551 .width('90%') 1552 .fontSize(16) 1553 .textAlign(TextAlign.Center) 1554 .borderRadius(10) 1555 .backgroundColor( this.itemBackgroundColorArr[item] ? 0x68B4FF: 0xFFFFFF) 1556 } 1557 }, (item: number) => item.toString()) 1558 } 1559 .backgroundColor(Color.Gray) 1560 .layoutWeight(1) 1561 .scrollBar(BarState.On) 1562 .childrenMainSize(this.listChildrenSize) 1563 .alignListItem(ListItemAlign.Center) 1564 .gesture( 1565 PanGesture() 1566 .onActionUpdate((event: GestureEvent) => { 1567 if (event.fingerList[0] != undefined && event.fingerList[0].localX != undefined && event.fingerList[0].localY != undefined) { 1568 this.listIndex = this.scroller.getItemIndex(event.fingerList[0].localX, event.fingerList[0].localY); 1569 this.itemBackgroundColorArr[this.listIndex] = true; 1570 } 1571 }) 1572 ) 1573 .gesture( 1574 TapGesture({ count: 1 }) 1575 .onAction((event: GestureEvent) => { 1576 if (event) { 1577 this.itemBackgroundColorArr.splice(0,this.itemBackgroundColorArr.length); 1578 } 1579 }) 1580 ) 1581 1582 Text('您当前位置Item索引为：'+ this.listIndex) 1583 .fontColor(Color.Red) 1584 .height(50) 1585 } 1586 } 1587} 1588``` 1589 1590 1591 1592### 示例7（设置边缘渐隐） 1593该示例实现了Scroll组件开启边缘渐隐效果并设置边缘渐隐长度。 1594 1595```ts 1596// xxx.ets 1597import { LengthMetrics } from '@kit.ArkUI'; 1598@Entry 1599@Component 1600struct ScrollExample { 1601 scroller: Scroller = new Scroller(); 1602 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]; 1603 1604 build() { 1605 Stack({ alignContent: Alignment.TopStart }) { 1606 Scroll(this.scroller) { 1607 Column() { 1608 ForEach(this.arr, (item: number) => { 1609 Text(item.toString()) 1610 .width('90%') 1611 .height(150) 1612 .backgroundColor(0xFFFFFF) 1613 .borderRadius(15) 1614 .fontSize(16) 1615 .textAlign(TextAlign.Center) 1616 .margin({ top: 10 }) 1617 }, (item: string) => item) 1618 }.width('100%') 1619 } 1620 .fadingEdge(true,{fadingEdgeLength:LengthMetrics.vp(80)}) 1621 1622 1623 1624 }.width('100%').height('100%').backgroundColor(0xDCDCDC) 1625 } 1626} 1627``` 1628 1629 1630 1631### 示例8（单边边缘效果） 1632 1633该示例通过edgeEffect接口，实现了Scroll组件设置单边边缘效果。 1634 1635```ts 1636// xxx.ets 1637@Entry 1638@Component 1639struct ScrollExample { 1640 scroller: Scroller = new Scroller(); 1641 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]; 1642 1643 build() { 1644 Stack({ alignContent: Alignment.TopStart }) { 1645 Scroll(this.scroller) { 1646 Column() { 1647 ForEach(this.arr, (item: number) => { 1648 Text(item.toString()) 1649 .width('90%') 1650 .height(150) 1651 .backgroundColor(0xFFFFFF) 1652 .borderRadius(15) 1653 .fontSize(16) 1654 .textAlign(TextAlign.Center) 1655 .margin({ top: 10 }) 1656 }, (item: string) => item) 1657 }.width('100%') 1658 } 1659 .edgeEffect(EdgeEffect.Spring,{alwaysEnabled:true,effectEdge:EffectEdge.START}) 1660 }.width('100%').height('100%').backgroundColor(0xDCDCDC) 1661 } 1662} 1663``` 1664 1665 1666 1667### 示例9（划动翻页效果） 1668 1669该示例通过enablePaging接口，实现了Scroll组件划动翻页效果。 1670 1671```ts 1672// xxx.ets 1673@Entry 1674@Component 1675struct EnablePagingExample { 1676 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1677 1678 build() { 1679 Stack({ alignContent: Alignment.Center }) { 1680 Scroll() { 1681 Column() { 1682 ForEach(this.arr, (item: number) => { 1683 Text(item.toString()) 1684 .width('100%') 1685 .height('100%') 1686 .borderRadius(15) 1687 .fontSize(16) 1688 .textAlign(TextAlign.Center) 1689 .backgroundColor(0xFFFFFF) 1690 }, (item: number) => item.toString()) 1691 } 1692 }.width('90%').height('90%') 1693 .enablePaging(true) 1694 }.width('100%').height('100%').backgroundColor(0xDCDCDC) 1695 } 1696} 1697``` 1698 1699 1700 1701### 示例10（设置过界停留） 1702 1703该示例通过scrollTo接口，实现了Scroll组件设置过界停留效果。 1704 1705```ts 1706// xxx.ets 1707import { curves } from '@kit.ArkUI'; 1708 1709@Entry 1710@Component 1711struct StickyNestedScroll { 1712 scroller: Scroller = new Scroller; 1713 1714 build() { 1715 Column() { 1716 Row() { 1717 Button('有动画scrollTo').onClick(() => { 1718 let curve = curves.interpolatingSpring(0.5, 5, 10, 15) //创建一个弹簧曲线 1719 const yOffset: number = this.scroller.currentOffset().yOffset; 1720 this.scroller.scrollTo({ 1721 xOffset: 0, 1722 yOffset: yOffset - 100, 1723 animation: { duration: 1000, curve: curve, canOverScroll: true }, 1724 canOverScroll: true 1725 }) 1726 }).margin({ top: 10 }) 1727 Button('无动画scrollTo').onClick(() => { 1728 const yOffset: number = this.scroller.currentOffset().yOffset; 1729 this.scroller.scrollTo({ 1730 xOffset: 0, 1731 yOffset: yOffset - 100, 1732 animation: false, 1733 canOverScroll: true 1734 }) 1735 }).margin({ top: 10, left: 20 }) 1736 }.margin({ bottom: 20 }) 1737 1738 Scroll(this.scroller) { 1739 Column() { 1740 Text('Scroll Area') 1741 .width('100%') 1742 .height('100%') 1743 .backgroundColor('#0080DC') 1744 .textAlign(TextAlign.Center) 1745 } 1746 .width('100%') 1747 .height('100%') 1748 } 1749 .scrollable(ScrollDirection.Vertical) 1750 .edgeEffect(EdgeEffect.Spring) //设置边缘效果 1751 .fadingEdge(false) //关闭边缘渐隐效果 1752 .scrollBar(BarState.Auto) 1753 .friction(undefined) 1754 .backgroundColor('#DCDCDC') 1755 .width('100%') 1756 .height('50%') 1757 } 1758 } 1759} 1760``` 1761 1762 1763 1764 1765### 示例11（自由滚动和缩放） 1766 1767该示例实现了Scroll组件自由滚动和缩放效果。 1768```ts 1769@Entry 1770@Component 1771struct ScrollZoomExample { 1772 @State currScale:number = 1; 1773 build() { 1774 Column() { 1775 Scroll() { 1776 Image($r('app.media.image1')) // 'app.media.image1'仅作示例，请替换实际图片。 1777 } 1778 .height(400) 1779 .scrollable(ScrollDirection.FREE) 1780 .minZoomScale(1) 1781 .maxZoomScale(2) 1782 .zoomScale(this.currScale!!) 1783 .enableBouncesZoom(true) 1784 .onDidZoom((scale: number) => { 1785 console.info(`onDidZoom:${scale}`); 1786 }) 1787 .onZoomStart(() => { 1788 console.info('onZoomStart'); 1789 }) 1790 .onZoomStop(() => { 1791 console.info('onZoomStop'); 1792 }) 1793 }.width('100%').height('100%') 1794 } 1795} 1796``` 1797 1798
