Scroller(滚动容器)
Scroller(滚动容器)
用于展示不确定高度的内容，可以将一系列不确定高度的子组件装到一个确定高度的容器中，使用者可通过上下或左右滚动操作查看组件宽高之外的内容。
属性
除了支持所有基础属性，还支持以下属性：
scrollEnable
是否允许滑动内容
| 参数 | 描述 | 类型 |
|---|---|---|
| scrollEnable | 是否允许滑动内容，默认true | Boolean |
bouncesEnable H5实现中 微信小程序实现中
是否开启回弹效果
| 参数 | 描述 | 类型 |
|---|---|---|
| bouncesEnable | 是否开启回弹效果，默认 true | Boolean |
showScrollerIndicator
是否显示滚动条
| 参数 | 描述 | 类型 |
|---|---|---|
| showScrollerIndicator | 是否显示滚动条，默认 true | Boolean |
flexDirection
指定排版方向
| 参数 | 描述 | 类型 |
|---|---|---|
| flexDirection | 指定排版方向，FlexDirection.COLUMN为垂直方向，FlexDirection.Row为水平方向，默认为垂直方向 | FlexDirection |
pagingEnable
是否开启分页
| 参数 | 描述 | 类型 |
|---|---|---|
| pagingEnable | 是否开启分页 | Boolean |
nestedScroll
设置子滚动容器的嵌套滚动模式，用于控制父子滚动容器之间的滚动行为
| 参数 | 描述 | 类型 |
|---|---|---|
| forward | 向前滚动（向上/向左）时的嵌套滚动模式 | KRNestedScrollMode |
| backward | 向后滚动（向下/向右）时的嵌套滚动模式 | KRNestedScrollMode |
KRNestedScrollMode 枚举值：
| 值 | 描述 |
|---|---|
| SELF_ONLY | 仅当前控件处理滚动，不传递给父控件 |
| SELF_FIRST | 当前控件优先处理滚动，未消费完的滚动量传递给父控件 |
| PARENT_FIRST | 父控件优先处理滚动，未消费完的滚动量传递给当前控件 |
| 用法参考：竖向列表嵌套滚动用法示例、 | |
| 横向列表嵌套滚动示例 |
visibleAreaIgnoreTopMargin
设置计算子组件可见性面积时忽略的顶部距离。用于配合 willAppear、didAppear、willDisappear、didDisappear、appearPercentage 等可见性事件使用。
| 参数 | 描述 | 类型 |
|---|---|---|
| margin | 计算可见性时忽略的顶部距离，单位为 dp | Float |
visibleAreaIgnoreBottomMargin
设置计算子组件可见性面积时忽略的底部距离。用于配合 willAppear、didAppear、willDisappear、didDisappear、appearPercentage 等可见性事件使用。
| 参数 | 描述 | 类型 |
|---|---|---|
| margin | 计算可见性时忽略的底部距离，单位为 dp | Float |
使用场景
当滚动容器顶部或底部有固定的遮挡区域（如悬浮导航栏、底部工具栏等）时，可以使用这两个属性来调整可见性计算的有效区域，确保子组件的可见性事件触发更加准确。
事件
除了支持所有基础事件，还支持以下事件：
scroll
监听滚动事件，该方法接收一个闭包回调, 回调中的参数为 ScrollParams
ScrollParams
| 参数 | 描述 | 类型 |
|---|---|---|
| offsetX | 列表当前横轴偏移量 | Float |
| offsetY | 列表当前纵轴偏移量 | Float |
| contentWidth | 列表当前内容总宽度 | Float |
| contentHeight | 列表当前内容总高度 | Float |
| viewWidth | 列表View宽度 | Float |
| viewHeight | 列表View高度 | Float |
| isDragging | 当前是否处于拖拽列表滚动中 | Boolean |
scrollEnd
滚动结束时事件, 该方法接收一个闭包回调, 回调中的参数为 ScrollParams
ScrollParams
| 参数 | 描述 | 类型 |
|---|---|---|
| offsetX | 列表当前横轴偏移量 | Float |
| offsetY | 列表当前纵轴偏移量 | Float |
| contentWidth | 列表当前内容总宽度 | Float |
| contentHeight | 列表当前内容总高度 | Float |
| viewWidth | 列表View宽度 | Float |
| viewHeight | 列表View高度 | Float |
| isDragging | 当前是否处于拖拽列表滚动中 | Boolean |
dragBegin
用户开始拖拽事件, 该方法接收一个闭包回调, 回调中的参数为 ScrollParams
ScrollParams
| 参数 | 描述 | 类型 |
|---|---|---|
| offsetX | 列表当前横轴偏移量 | Float |
| offsetY | 列表当前纵轴偏移量 | Float |
| contentWidth | 列表当前内容总宽度 | Float |
| contentHeight | 列表当前内容总高度 | Float |
| viewWidth | 列表View宽度 | Float |
| viewHeight | 列表View高度 | Float |
| isDragging | 当前是否处于拖拽列表滚动中 | Boolean |
dragEnd
用户停止拖拽事件, 该方法接收一个闭包回调, 回调中的参数为 ScrollParams
ScrollParams
| 参数 | 描述 | 类型 |
|---|---|---|
| offsetX | 列表当前横轴偏移量 | Float |
| offsetY | 列表当前纵轴偏移量 | Float |
| contentWidth | 列表当前内容总宽度 | Float |
| contentHeight | 列表当前内容总高度 | Float |
| viewWidth | 列表View宽度 | Float |
| viewHeight | 列表View高度 | Float |
| isDragging | 当前是否处于拖拽列表滚动中 | Boolean |
scrollToTop
监听系统触发的“回到顶部”事件。仅 iOS 会在点击状态栏时触发，默认会拦截系统自动滚动到顶部的行为，需在回调中自行处理（如调用 setContentOffset）。
| 参数 | 描述 | 类型 |
|---|---|---|
| 无 | 回调无参数 | - |
contentSizeChanged
组件 Size 发生变化事件, 该方法接收一个闭包回调, 回调中的参数如下
| 参数 | 描述 | 类型 |
|---|---|---|
| width | 组件宽度 | Float |
| height | 组件高度 | Float |
方法
setContentOffset
设置Scroller滚动到某个具体坐标偏移值(offset)的位置。
| 参数 | 描述 | 类型 |
|---|---|---|
| offsetX | 滚动到x轴的偏移量 | Float |
| offsetY | 滚动到y轴的偏移量 | Float |
| animated | 滚动到y轴的偏移量, 默认为false | Boolean |
| springAnimation | 是否使用spring动画滚动, 默认为null | SpringAnimation |
setContentInset
设置Scroller内容边距
| 参数 | 描述 | 类型 |
|---|---|---|
| top | 上边距 | Float |
| left | 左边距 | Float |
| bottom | 下边距 | Float |
| right | 右边距 | Float |
| animated | 滑动过程是否使用动画, 默认false | Boolean |
setContentInsetWhenEndDrag
设置 OverScroll 时停留的内容边距
| 参数 | 描述 | 类型 |
|---|---|---|
| top | 上边距 | Float |
| left | 左边距 | Float |
| bottom | 下边距 | Float |
| right | 右边距 | Float |