# UIScrollView 滑动组件

# 概述

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

# 组件概要

UIScrollView -> Touchable -> Component -> Object

# 滑动距离计算

默认情况下，滑动距离是根据，内容区域大小（一级子节点的最大节点大小）与滑动区域大小（对应Transform2D大小）的差值得来，滑动距离的结果会保存于 minContextMove 与 maxContextMove。

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

# 内容区域定位

内容区域定位分为：用户定位模式 与 自动定位模式。

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

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

# 注意

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

# 静态属性描述

属性	功能
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滑动

# 使用流程

/* UIScrollView1 */
// 标准的UIScrollView组件
const scrollView1Entity = game.createEntity2D('UIScrollView1');
scrollView1Entity.transform2D.position.x = -400;
scrollView1Entity.transform2D.position.y = 225;
scrollView1Entity.transform2D.anchor.y = 1;
// UIScrollView 及 UIMask 依据所在节点的size进行滑动区域运算与蒙层运算
scrollView1Entity.transform2D.size.x = 200;
scrollView1Entity.transform2D.size.y = 450;
// 添加ScrollView控制组件
const scrollView1 = scrollView1Entity.addComponent(engine.UIScrollView);
// 以垂直方向进行滑动控制
scrollView1.movement = engine.UIScrollView.MovementType.Vertical;
// 添加触摸组件
const scrollView1Touch = scrollView1Entity.addComponent(engine.TouchInputComponent);
// 添加蒙层组件
const scrollView1Mask = scrollView1Entity.addComponent(engine.UIMask);
// 添加蒙层组件需要的 渲染区域
const scrollView1Graphic = scrollView1Entity.addComponent(engine.UIGraphic);
uiRoot.addChild(scrollView1Entity.transform2D);

// UIScrollView1 所在节点的子节点 UIGrid1
const grid1Entity = game.createEntity2D('UIGrid1');
grid1Entity.transform2D.anchor.y = 1;
const grid1 = grid1Entity.addComponent(engine.UIGrid);
grid1.cellWidth = 200;
grid1.cellHeight = 100;
grid1.arrangement = engine.UIGrid.Arrangement.Vertical;
for (let i = 1; i < 7; i++) {
    const gridItem = game.createEntity2D('UIGrid1.' + i);
    gridItem.transform2D.size.x = 200;
    gridItem.transform2D.size.y = 100;
    const gridItemGraphic = gridItem.addComponent(engine.UIGraphic);
    gridItemGraphic.color = new engine.Color(i * 123 % 255, i * 88 % 255, i * 168 % 255);
    grid1Entity.transform2D.addChild(gridItem.transform2D);

}
scrollView1Entity.transform2D.addChild(grid1Entity.transform2D);

/* UIScrollView2 */
// 不添加 Mask 组件，让 UIGraphic 显示实际 UIScrollView 区域大小
const scrollView2Entity = game.createEntity2D('UIScrollView2');
scrollView2Entity.transform2D.position.x = 200;
scrollView2Entity.transform2D.size.x = 600;
scrollView2Entity.transform2D.size.y = 400;
const scrollView2 = scrollView2Entity.addComponent(engine.UIScrollView);
// 开启 UIScrollView 根据信息与配置，将内容区域设置到对应位置的逻辑
scrollView2.autoFix = true;
// autoFix 下内容区域相对于滑动区域左对齐
scrollView2.cellAlignmentX = 0;
// autoFix 下内容区域相对于滑动区域下对齐
scrollView2.cellAlignmentY = 0;
// 滑动到起点边界时，禁止往起点外滑动
scrollView2.snapToStart = true;
// 滑动到终点边界时，禁止往终点外滑动
scrollView2.snapToEnd = true;
// 以水平方向进行滑动控制
scrollView2.movement = engine.UIScrollView.MovementType.Horizontal;
const scrollView2Touch = scrollView2Entity.addComponent(engine.TouchInputComponent);
// 不添加 Mask 组件，让 UIGraphic 显示实际 UIScrollView 区域大小
const scrollView2Graphic = scrollView2Entity.addComponent(engine.UIGraphic);
uiRoot.addChild(scrollView2Entity.transform2D);

// UIScrollView2 所在节点的子节点 UIGrid2
const grid2Entity = game.createEntity2D('UIGrid2');
const grid2 = grid2Entity.addComponent(engine.UIGrid);
grid2.cellWidth = 200;
grid2.cellHeight = 100;
for (let i = 1; i < 5; i++) {
    const gridItem = game.createEntity2D('UIGrid2.' + i);
    gridItem.transform2D.size.x = 200;
    gridItem.transform2D.size.y = 100;
    const gridItemGraphic = gridItem.addComponent(engine.UIGraphic);
    gridItemGraphic.color = new engine.Color(i * 123 % 255, i * 88 % 255, i * 168 % 255);
    grid2Entity.transform2D.addChild(gridItem.transform2D);
}
scrollView2Entity.transform2D.addChild(grid2Entity.transform2D);