# UIScrollView 滑动组件

# 概述

UIScrollView 是带有 滚动功能的控制组件,根据自身以及内容区域的信息,实现控制内容区域滑动的效果。

UIScrollView.gif

# 静态属性描述

Movement :UIScrollView具有的滑动方向类型枚举值

// engine.UIScrollView.Movement
enum Movement {
  Horizontal,
  Vertical
}

# 属性描述

属性名 类型 默认值 说明
movement Movement Movement.Vertical UIScrollView的滑动方向。
minContextMove number 0 相对于滑动起点的,最小滑动距离,若设定,则 UIScrollView 自动计算最小滑动距离逻辑失效,最小值固定取该值。
maxContextMove number 0 相对于滑动起点的,最大滑动距离,若设定,则 UIScrollView 自动计算最大滑动距离逻辑失效,最大值固定取该值。
moveDistance number 0 只读属性,相对于滑动起点,正向的已滑动的距离。
disableDragIfFits boolean true 内容区域尺寸小于滑动区域(对应Transform2D大小)时,是否禁止滑动。
snapToStart boolean false 滑动到顶后(小于minContentMove),是否允许继续滑动
snapToEnd boolean false 滑动到底后(大于maxContentMove),是否允许继续滑动
autoFix boolean false 是否开启组件根据内容区域大小与滑动区域大小(对应Transform2D大小),将内容区域移动到相对于当前组件的对齐位置,内容区域只会根据 UIScrollView 第一层子元素大小进行位置适配。
cellAlignmentX number 0 在 autoFix 情况下,内容区域位于滑动区域(对应Transform2D大小)水平方向的相对位置,取值范围(0-1)。
cellAlignmentY number 1 在 autoFix 情况下,内容区域位于滑动区域(对应Transform2D大小)垂直方向的相对位置,取值范围(0-1)。

# 方法描述

方法 参数 返回值 功能
onReachStart Delegate<this, TouchInputEvent> 返回 UIScrollView 到顶行为的Delegate,通过 add 方法添加事件。
onReachEnd Delegate<this, TouchInputEvent> 返回 UIScrollView 到底行为的Delegate,通过 add 方法添加事件。
setMinMax <min: number, max: number> 设置设定的最大最小滑动距离,若设定则优先使用这两个值。
clearMinMax 清理设定的最大最小,取消后会恢复使用自动生成最大最小距离逻辑。
scrollTo <pos: number> 组件滑动到,pos对应的滑动距离
refreshMove 清空当前滑动了的距离,并重新初始化
enableScroll 开启 UIScrollView 滑动
disableScroll 暂停 UIScrollView 滑动

# 滑动距离计算

默认情况下,滑动距离是根据,内容区域大小(一级子节点的最大节点大小)与滑动区域大小(对应Transform2D大小)的差值得来,滑动距离的结果会保存于 minContextMovemaxContextMove

若用户设定了 minContextMoveminContextMove,则会根据用户设定的值进行滑动距离的判断。若需恢复自动判断滑动距离的逻辑,调用组件 clearMinMax 方法即可。

# 内容区域定位

内容区域定位分为:用户定位模式自动定位模式

默认情况下,为用户定位模式,组件会以初始化时的子节点状态作为起始滑动状态。

autoFixture,为自动定位模式,组件会根据内容区域信息(最大子节点大小、锚点)与滑动区域信息(对应Transform2D大小,锚点)及配置信息(cellAlignmentX、cellAlignmentY),将内容区域位置调整到相对于滑动区域的对齐位置

# 注意

UIScrollView 仅为控制组件。一般情况下需要在同一节点结合:点击控制组件TouchInputComponent蒙层组件UIMask与蒙层组件对应渲染区域的图形组件UIGraphic,协同使用。

# 使用方法

# 代码使用

// 标准的 UIScrollView 组件
const scrollViewEntity = game.createEntity2D('UIScrollView');
// 添加 ScrollView 控制组件
const scrollView = scrollViewEntity.addComponent(engine.UIScrollView);
// 以垂直方向进行滑动控制
scrollView.movement = engine.UIScrollView.MovementType.Vertical;
// 添加触摸组件
const scrollViewTouch = scrollViewEntity.addComponent(engine.TouchInputComponent);
// 添加蒙层组件
const scrollViewMask = scrollViewEntity.addComponent(engine.UIMask);
// 添加蒙层组件需要的 渲染区域
const scrollViewGraphic = scrollViewEntity.addComponent(engine.UIGraphic);
uiRoot.addChild(scrollViewEntity.transform2D);

# 编辑器使用

右键 - UI - 新建ScrillView

# 使用案例

制作按钮与滚动列表