本文同步发表于 微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

一、Scroll 组件

Scroll 是 HarmonyOS ArkUI 框架中的可滚动容器组件，用于承载可滚动内容。当子组件的布局尺寸超过父组件的尺寸时，内容可以滚动。

核心特性

• API 版本：从 API version 7 开始支持

• 设备支持：Phone、PC、2in1、Tablet、TV、Wearable

• 滚动前提：主轴方向大小小于内容大小

• 子组件限制：支持单个子组件

  • API 21+：子组件宽高最大为 16777216px

  • API 20 及之前：子组件宽高最大为 1000000px

注意事项

1. 嵌套 List 性能优化：Scroll 嵌套 List 时，若 List 不设置宽高，默认全部加载。性能敏感场景建议指定 List 的宽高

2. clip 属性：默认值为 true

3. 高度自适应：高度超出屏幕时，可使用 layoutWeight 让 Scroll 高度适应主轴剩余空间

4. 动画停止机制：手指触摸屏幕时，会停止当前触摸范围内滚动组件的滚动动画（scrollTo 和 scrollToIndex 触发的动画除外）

5. 手势处理：组件已绑定手势实现跟手滚动，增加自定义手势需参考手势拦截

二、接口与构造函数

2.1 Scroll 构造函数

Scroll(scroller?: Scroller)

• 参数：

  • scroller：可滚动组件的控制器（可选）

• 说明：

  • 不允许和其他滚动类组件（ArcList、List、Grid、Scroll、WaterFlow）绑定同一个滚动控制对象

• 元服务支持：API version 11+

三、核心属性

3.1 滚动方向控制

scrollable(value: ScrollDirection)

设置滚动方向，修改后会重置滚动偏移量

• 默认值：ScrollDirection.Vertical

• 枚举值：

  • Vertical (0)：仅竖直方向滚动

  • Horizontal (1)：仅水平方向滚动

  • FREE (4)：自由滚动（API 20+，替代已废弃的 Free）

  • None (3)：不可滚动

FREE 模式限制：

• 支持属性：scrollBar、scrollBarColor、scrollBarWidth、scrollBarMargin、edgeEffect、enableScrollInteraction、friction、clipContent、initialOffset、scrollable

• 支持事件：onWillScroll、onDidScroll、onScrollEdge、onScrollStart、onScrollStop

• 支持 Scroller 接口：scrollTo、scrollEdge、scrollPage、currentOffset、scrollBy、getItemRect

3.2 滚动条控制

3.2.1 scrollBar(barState: BarState)

设置滚动条状态

• 默认值：BarState.Auto

• 特性：

  • 容器无法滚动时不显示滚动条

  • 子组件大小为无穷大时，滚动条不支持拖动和伴随滚动

  • API 10+：存在圆角时，滚动条自动计算避让距离

3.2.2 scrollBarColor(color: Color | number | string | Resource)

设置滚动条颜色

• 默认值：'#66182431'

• API 22+：支持 Resource 类型

3.2.3 scrollBarWidth(value: number | string)

设置滚动条宽度

• 默认值：4vp

• 取值范围：

  • 小于 0：按默认值处理

  • 等于 0：不显示滚动条

• 限制：宽度超过 Scroll 主轴方向高度时，会变为默认值

3.3 边缘效果

edgeEffect(edgeEffect: EdgeEffect, options?: EdgeEffectOptions)

设置边缘滑动效果

• 默认值：EdgeEffect.None

• 效果类型：

  • Spring：弹簧效果

  • Fade：阴影效果

  • None：无效果

• options：

  • alwaysEnabled：组件内容小于自身时是否开启滑动效果

  • effectEdge：单边效果（如 EffectEdge.START）

3.4 嵌套滚动

nestedScroll(value: NestedScrollOptions)

设置嵌套滚动模式

• 默认值：{ scrollForward: NestedScrollMode.SELF_ONLY, scrollBackward: NestedScrollMode.SELF_ONLY }

• 限制：

  • Scroll 设置 enablePaging 或 scrollSnap 并同时设置父组件优先的嵌套滚动时，嵌套滚动不生效

3.5 限位滚动

scrollSnap(value: ScrollSnapOptions)

设置限位滚动模式

• 触发条件：限位动画期间 onWillScroll 事件上报的滚动操作来源类型为 ScrollSource.FLING

• ScrollSnapOptions：

  • snapAlign：对齐方式（默认 ScrollSnapAlign.NONE）

  • snapPagination：分页点（Dimension 或 Array<Dimension>）

  • enableSnapToStart：是否允许在开头和第一页间自由滑动（默认 true）

  • enableSnapToEnd：是否允许在最后一页和末尾间自由滑动（默认 true）

3.6 摩擦系数

friction(value: number | Resource)

设置摩擦系数，仅影响手动划动时的惯性滚动

• 默认值：

  • 可穿戴设备：0.9

  • 非可穿戴设备：

    • API 11+：0.7

    • API 12+：0.75

    • 早期：0.6

• 取值范围：(0, +∞)，小于等于 0 时按默认值处理

3.7 翻页功能

enablePaging(value: boolean)

设置是否支持划动翻页

• 默认值：false

• 优先级：如果同时设置 enablePaging 和 scrollSnap，scrollSnap 优先生效

3.8 初始偏移

initialOffset(value: OffsetOptions)

设置初始滚动偏移量

• 生效时机：只在首次布局时生效，后续动态修改不生效

• 百分比处理：当输入大小为百分比时，初始滚动偏移量为 Scroll 组件主轴方向大小与百分比数值之积

3.9 缩放功能（API 20+）

3.9.1 maxZoomScale(scale: number)

设置最大手势缩放比例

• 默认值：1

• 取值范围：(0, +∞)，小于等于 0 时按默认值 1 处理

3.9.2 minZoomScale(scale: number)

设置最小手势缩放比例

• 默认值：1

• 取值范围：(0, maxZoomScale]，小于等于 0 时按默认值 1 处理，大于 maxZoomScale 时按 maxZoomScale 处理

3.9.3 zoomScale(scale: number)

设置缩放比例

• 默认值：1

• 取值范围：(0, +∞)，小于等于 0 时按默认值 1 处理

• 特性：支持双向绑定变量

3.9.4 enableBouncesZoom(enable: boolean)

启用过缩放回弹效果

• 默认值：true

缩放启用条件：maxZoomScale 和 minZoomScale 不同时为 1 时启用缩放手势

3.10 交互控制

enableScrollInteraction(value: boolean)

设置是否支持滚动手势

• 默认值：true

• 说明：

  • true：可以通过手指或鼠标滚动

  • false：无法通过手指或鼠标滚动，但不影响 Scroller 控制器的滚动接口

• 限制：组件无法通过鼠标按下拖动操作进行滚动

四、事件系统

Scroll 组件支持通用事件、滚动组件通用事件，以及以下特有事件：

4.2 滚动生命周期事件

4.2.1 onScrollFrameBegin

触发时机：每帧滚动开始前回调

onScrollFrameBegin(event: OnScrollFrameBeginCallback)
type OnScrollFrameBeginCallback = (offset: number, state: ScrollState) => OnScrollFrameBeginHandlerResult

• 功能：拦截并修改即将发生的滚动量

• 返回值：{ offsetRemain: number }（支持负值）

• 触发条件：

  • 用户交互（手指滑动、键鼠操作）

  • Scroll 惯性滚动

  • 调用 fling() 接口

• 不触发条件：

  • 调用除 fling 外的其他滚动控制接口

  • 越界回弹

  • 拖动滚动条

• 嵌套滚动关键：需设置子滚动节点的 EdgeEffect 为 None

4.2.2 onWillScroll（推荐替代 onScroll）

触发时机：滚动前触发

onWillScroll(handler: ScrollOnWillScrollCallback)
type ScrollOnWillScrollCallback = (xOffset: number, yOffset: number, scrollState: ScrollState, scrollSource: ScrollSource) => void | OffsetResult

• 功能：回调将要滚动的偏移量（非最终实际滚动偏移），可返回自定义偏移量

• 性能警告：此回调触发频繁，应避免耗时操作

• 触发条件：

  • 滚动组件触发滚动

  • 通过滚动控制器 API 调用

  • 越界回弹

4.2.3 onDidScroll

触发时机：滚动时触发

onDidScroll(handler: ScrollOnScrollCallback)
type ScrollOnScrollCallback = (xOffset: number, yOffset: number, scrollState: ScrollState) => void

4.2.4 onScroll（已废弃）

说明：从 API 12 开始废弃，建议使用 onWillScroll 替代

4.2.5 onScrollEdge

触发时机：滚动到边缘时触发

onScrollEdge(event: OnScrollEdgeCallback)
type OnScrollEdgeCallback = (side: Edge) => void

• 废弃说明：Edge.Center 和 Edge.Baseline 已废弃，推荐使用 onReachStart 和 onReachEnd

4.2.6 onScrollStart

触发时机：滚动开始时触发

4.2.7 onScrollStop / onScrollEnd

触发时机：滚动停止时触发

• 注意：onScrollEnd 已废弃（API 9+），建议使用 onScrollStop

4.3 缩放事件（API 20+）

4.3.1 onDidZoom

触发时机：每帧缩放完成时触发

onDidZoom(event: ScrollOnDidZoomCallback)
type ScrollOnDidZoomCallback = (scale: number) => void

4.3.2 onZoomStart

触发时机：手势缩放开始触发

4.3.3 onZoomStop

触发时机：手势缩放停止时触发

总结

Scroll 组件是 HarmonyOS ArkUI 中的滚动容器，提供了：

1. 完整的滚动控制：支持垂直、水平、自由方向滚动

2. 丰富的交互效果：边缘回弹、渐隐、缩放、限位滚动、翻页

3. 灵活的事件系统：从滚动开始到结束的完整生命周期事件

4. 强大的控制器：Scroller 提供编程式滚动控制

5. 高级功能：嵌套滚动、动态事件绑定、内容大小查询

6. 性能优化：懒加载支持、高频回调优化、内存管理

Scroller控制器：