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