UIScrollView 滑动组件

概述

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

组件概要

UIScrollView -> Touchable -> Component -> Object

滑动距离计算

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

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

内容区域定位

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

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

autoFixture,为自动定位模式,组件会根据内容区域信息(最大子节点大小、锚点)与滑动区域信息(对应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滑动

使用流程

UIScrollView.gif

/* 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);