这是一个基于Cocos Creator写的虚拟列表组件。本组件是配合Cocos Creator本身的滚动窗结构去写的,所以在编辑器中操作会很方便,所见即所得。
在线DEMO:
Cocos论坛帖子链接:
- 所有类型布局。(单列、单行、网格,甚至各种花式RIGHT_TO_LEFT、BOTTOM_TO_TOP)
- 分帧渲染。
- 循环列表。
- 选择模式。(单选、多选)
- 滑动模式。(普通、粘附、分页)
- 自定义Item的宽/高。(用来做聊天列表再适合不过)
- 动态删除Item项。
- ...
Last test by ccc_v2.2.1
我的邮箱:klk0@qq.com
- 在编辑器中,创建一个ScrollView(也就是ScrollView->Mask->Content这样层级结构的节点!)。
- 将
List
组件挂载到ScrollView节点上。 - 设置模板Item,选择
TemplateType
,可切换模板类型,请按需选择。 - 设置滑动模式(
SlideMode
),NORMAL=通常
,ADHERING=粘附
,PAGE=分页
,三选一。 - 设置是否为虚拟列表(
Virtual
),默认为true
,意思是仅在可视范围内渲染Item
。反之,如果为false
,则会渲染所有数量的Item,一般不推荐这么做,但凡事总有个万一,所以预留了。 - 可选设置逐帧渲染(
FrameByFrameRenderNum
),该数量为每帧渲染的数量。 - 设置渲染器(
RenderEvent
),在View中写一个函数,将该函数指向RenderEvent,运行时,设置List数量,Item将会通过该函数进行回调,开发者在该函数中实现Item的刷新。 - 可选设置选择模式(
SelectedMode
),选择模式有SINGLE(单选)
、MULT(多选)
两种模式,须与ListItem
组件搭配使用,ListItem
组件需要拖拽到模板Item上。在View中写一个函数,将该函数指向SelectedEvent
,运行时,当选择变更,将会通过该函数回调。
在View中,若是单选模式,用
list.selectedId=Number
来改变当前选择。若是多选模式,则调用list.setMultSelected(args, boolean)
接口来设置多选数据。
- 完成以上设置后,在View中调用
list.numItems=Number
设置列表数量,本组件就会通过渲染器(即RenderEvent
)进行回调了!
- 每一个
Item-Node
都会被赋值一个_listId
,即该Item
在List
中的下标
。假如你的Item
是个按钮
,在该按钮
的回调事件
中,通过event.currentTarget._listId
就能取得该Item的下标
了,这非常方便。(TS版
比较特殊, 通过event.currentTarget['_listId']
来获得。) - 在View中设置
list.customSize
以达到每个Item宽度或高度不一样的虚拟列表效果,简直美滋滋!但这个会耗费更多性能!仅支持虚拟列表!仅支持单列或单行!
- 本组件所依赖的ScrollView节点、Mask节点以及Content节点,这三个节点的锚点需要按方向去设置。比如从顶到底单列排列,就需要设置锚点为(0.5, 1)。如果是从左到右网格排列,就需要设置锚点为(0, 1)。始终将锚点设置到首个Item那一边。
- 理论上设为虚拟列表后不可再设回普通列表(即
virtual
属性)。 - SlideMode设为
ADHERING(粘附)
或PAGE(页面)
后,组件将强行屏蔽惯性滚动。 - 设为
循环列表
时,Content
的cc.Layout
的边缘距离(top/bottom/left/right)
要设置成与spacingX/Y(间距)
一样。(因为在循环列表中,边距=间距)
。
- 循环列表
PAGE
版。
PAGE
模式下,目前是靠pageDistance
变量来控制翻页响应距离
,如果滚动窗口很小,玩家拖动时一次性能拖(翻)1页以上,那就会存在问题。
示例项目升级至ccc_v2.2.1。
- 适配
cc.Widget
。 - 新增
TestWidget.scene
示例场景。 - 新增
循环列表
功能,即cyclic
属性。(目前仅支持单行/单列)
设为循环列表时,Content的cc.Layout边缘距离(top/bottom/left/right)要设置成与spacingX/Y(间距)一样。(因为在循环列表中,边距=间距)。
- 新增
TestCyclic.scene
示例场景。
- 新增
LakeSlide
属性。当该属性为true
,Item数量不足以填满Content
时,也可以滑动。(默认为false
,与LakeCenter
属性相斥)
- 修复
ListItem
可能会丢失事件的BUG。
示例项目升级至ccc_v2.2.0。
- 修复
List
销毁时,对象池中的Item
未执行销毁的BUG。 - 修复
PAGE
模式下,滑动翻页可能会跳页异常的BUG。 - 修复
模板Item
可能被误销毁的BUG。 - 修复当
List
节点的Size
改变时,List
未刷新的BUG。
- ccc_v2.2.0的cc.ScrollView有个BUG,就是滑动时,惯性滚动到边缘没有回弹效果,这不是本组件的问题,等待官方更新修复。
- 这个组件我也是佛系更新,只要官方的新版本不魔改,一般来说都是向上兼容的。
- 新增
背包
示例场景(TestBag.scene
)。
- TS版,
模板Item
取消强制挂载ListItem
,现可通过item['_listId']
来获取Item下标
。 - 新增
单选模式
下repeatEventSingle
属性,为true
时,可重复触发相同的单选事件。 - 修复滑动
ScollView
时,鼠标拖到ScollView
之外,会中止滚动的BUG。 - 修复
SlideMode
为PAGE
或ADHERING
时,滚动ScollView
容易卡住的BUG。
- 新增
TestCustomSize
场景例子,着重演示如何用本组件实现聊天列表
。 - 优化局部代码,提升一丁点效率。
- 将
updateAppointed
接口更名为updateItem
。 - 新增
updateAll()
接口。
- 新增
LakeCenter
属性。当该属性为true
,Item数量不足以填满Content
时,会居中显示所有Item。(不支持GRID
布局) - 新增
calcCustomSize
接口,方便开发者计算CustomSize
。(如果模板Item的结构较复杂,建议还是在外部自行计算) - 修复反方向布局,Item数量过少时,会向正方向对齐的BUG。
- 滑动模式新增
PAGE
模式,用来做分页效果,可自定义翻页滑动响应距离(pageDistance
)。建议不要再用ADHERING
模式去实现分页效果。关于PAGE
模式下的接口:list.prePage(timeInSecond)
、list.nextPage(timeInSecond)
、list.skipPage(pageNum, timeInSecond)
,分别是上一页、下一页、跳转到指定页数。 - 优化效率。
- 新增TS版本。
- 优化效率。
- 修复滑动模式为吸附(ADHERING)时,还未吸附到目标点时,点击滚动窗,再松开,会吸附失败的BUG。
- 独立吸附接口
list.adhere()
,可外部调用,不限滑动模式。
- 支持
BOTTOM_TO_TOP
,RIGHT_TO_LEFT
布局。需要注意:各种反方向排列的布局(BOTTOM_TO_TOP
、RIGHT_TO_LEFT
)都会有问题(item数量过少,就会导致Content错位),这个是官方问题。而本组件是配合cc.ScrollView
去写的,所以也不支持,待官方后续优化(Last test by Creator_v2.1.1)。如果Item数量很多,那么可以使用。
- 单列布局时支持自定义指定Item的height。单行布局时支持自定义指定Item的width。通过
list.customSize = {0:100, 1:130, 5:120, ...}
来设置,其中key为Item的ID,value为height/width,没有找到该Item的customSize将会与模板ItemSize一致。
- 新增List的配套组件----
ListItem
。 - 新增选择模式。
- 新增带动画删除Item接口
list.aniDelItem(id, callFunc, aniType)
,因本组件毕竟还是数据驱动,所以请务必在callFunc中删除数据数组中相应下标的数据,然后手动更新该list(即list.numItems=Number
)。