这是一个基于Cocos Creator写的虚拟列表组件。本组件是配合 Cocos Creator 本身的滚动窗结构去写的，所以在编辑器中操作会很方便，所见即所得。

在线 DEMO（请科学上网）：

主示例 页面模式示例 背包示例 聊天列表示例 循环列表示例

Cocos 论坛帖子链接：

https://forum.cocos.com/t/dc/79055

• 所有类型布局。（单列、单行、网格，甚至各种花式 RIGHT_TO_LEFT、BOTTOM_TO_TOP）
• 分帧渲染。
• 循环列表。
• 选择模式。（单选、多选）
• 滑动模式。（普通、粘附、分页）
• 动态 Item 宽/高。（用来做聊天列表再适合不过）
• 动态删除 Item 项。
• ...

Last test by ccc_v2.3.3

我的邮箱：[email protected]

1. 在编辑器中，创建一个ScrollView（也就是ScrollView->Mask->Content这样层级结构的节点！）。
2. 将 List 组件挂载到ScrollView节点上。
3. 设置模板 Item，选择 TemplateType ，可切换模板类型，请按需选择。
4. 设置滑动模式（ SlideMode ）， NORMAL=通常 ， ADHERING=粘附 ， PAGE=分页 ，三选一。
5. 设置是否为虚拟列表（ Virtual ），默认为 true ，意思是仅在可视范围内渲染 Item 。反之，如果为 false ，则会渲染所有数量的 Item，一般不推荐这么做，但凡事总有个万一，所以预留了。
6. （可选）设置逐帧渲染（ FrameByFrameRenderNum ），该数量为每帧渲染的数量。
7. 设置渲染器（ RenderEvent ），在View中写一个函数，将该函数指向RenderEvent，运行时，设置 List 数量，Item 将会通过该函数进行回调，开发者在该函数中实现Item 的刷新。
8. （可选）设置选择模式（ SelectedMode ），选择模式有 SINGLE（单选） 、 MULT（多选） 两种，须将cc.Button和ListItem 挂载到模板 Item上。在View中写一个函数，将该函数指向 SelectedEvent ，运行时，当选择变更，将会通过该函数回调。

在View中，若是单选模式，用 list.selectedId=Number 来改变当前选择。若是多选模式，则调用 list.setMultSelected(args, boolean) 接口来设置多选数据。

9. 完成以上设置后，在View中调用 list.numItems=Number 设置列表数量，本组件就会通过渲染器（即 RenderEvent ）进行回调了！

1. 每一个 Item-Node 都会被赋值一个 _listId ，即该 Item 在 List 中的 下标 。假如你的 Item 是个 按钮 ，在该 按钮 的 回调事件 中，通过 event.currentTarget._listId 就能取得该 Item的下标 了，这非常方便。（ TS版 比较特殊， 通过 event.currentTarget['_listId'] 来获得。）
2. 如果是虚拟列表（即 virtual属性为true），勾选ListItem的adaptiveSize属性，能实现动态Item宽/高。

1. 本组件所依赖的ScrollView 节点、Mask 节点以及Content 节点，这三个节点的锚点需要按方向去设置。比如从顶到底单列排列，就需要设置锚点为（0.5, 1）。如果是从左到右网格排列，就需要设置锚点为（0, 1）。始终将锚点设置到首个 Item那一边。
2. 理论上设为虚拟列表后不可再设回普通列表（即 virtual 属性）。
3. SlideMode 设为 ADHERING（粘附） 或 PAGE（页面） 后，组件将强行屏蔽惯性滚动。
4. 设为循环列表时，Content的cc.Layout的边缘距离（top/bottom/left/right）要设置成与spacingX/Y（间距）一样。（因为在循环列表中，边距=间距）。

• 下拉刷新。
• 循环列表PAGE版。

• PAGE模式下，目前是靠pageDistance变量来控制翻页响应距离，如果滚动窗口很小，玩家拖动时一次性能拖（翻）1 页以上，那就会存在问题。

模板 Item 类型，分别有 Node 和 Prefab 两种类型可选。

模板 Item 节点。

模板 Item 预制体。

滑动模式。分别有 3 种滑动模式：普通、粘附、页面。

翻页作用距离。（仅滑动模式为页面时有效）

翻页响应事件。

是否为虚拟列表。

是否为循环列表。

是否在 Item 数量不足以填满 Content 时，居中显示 Item（不支持 Grid 布局）。

是否在 Item 数量不足以填满 Content 时，可滑动列表。

刷新频率（值越大刷新频率越低、性能越高）。

分帧渲染时，每帧渲染的 Item 数量（<=0 时则关闭分帧渲染）。

渲染事件。

选择模式。分别有 2 种选择模式：单选、多选。

选择响应事件。

当前选择索引，可通过设置此属性变更选择。

Item 总数，设置此属性后，List 会调用 renderEvent 以渲染 Item。

可供开发者调用的方法都在下面，具体参数就不写了，去看源码吧 (￣ ▽ ￣)"。

设置模板 Item。

检查是否已初始化。

粘附到最近的一个 Item。

设置多选数据。

更新单个 Item。

更新全部 Item。

根据索引获取 Item。（虚拟列表有可能无法获取到 Item，因为 Item 可能并未出现在视口内）

动销删除单个 Item。（使用方法可参考示例项目）

滚动到指定索引 Item 处。

上一页。（仅滑动模式为 PAGE 时可用）

下一页。（仅滑动模式为 PAGE 时可用）

跳转至指定页。（仅滑动模式为 PAGE 时可用）

• 修复 TS 版单选/多选时，缺少参数的 BUG。（感谢 Cocos 论坛用户@455073646）

示例项目升级至 ccc_v2.3.2。（CocosDashboard 真香）

• 修复自适应宽/高（AdaptiveSize）时，调用List.scrollTo(...)可能会乱跳的 BUG。（感谢幻 <*****[email protected]>）

示例项目升级至 ccc_v2.3.1。

• 修改了模板Item的销毁机制，现在支持同一个View下，多个List的模板Item引用同一个Node。
• 修复使用自适应宽/高（AdaptiveSize）时，可能显示不完全的 Bug。（感谢 Cocos 论坛用户@icicic）
• 优化分帧加载（FrameByFrameRenderNum）时，滚动时刷新频率过高的问题。（感谢 Cocos 论坛用户@lifeiying）
• 优化选择模式（SelectedMode）的使用习惯。现在允许将按钮组件挂载到模板Item下的子节点上，当然，这样用的话，需要自行添加模板Item的ListItem的onClickThis到该按钮组件的Click Events上。

示例项目升级至 ccc_v2.2.2。

• 修复连续调用两次scrollTo可能会卡住的 BUG。
• 修复Selected Event报错。

• 以后都不推荐在外部计算customSize或是手动调用calcCustomSize函数。 现在要实现动态宽/高，请给模板Item挂载ListItem组件，并勾选adaptiveSize属性即可，惊不惊喜，意不意外？使用方法请看示例项目中的TestAdaptive场景。（感谢 Cocos 论坛用户@bluesn给出的建议）

  另外，List.customSize变量已更名为_customSize。calcCustomSize函数将会持续保留，某些特殊场景还是用得到的。

• 解决List销毁时，有可能存在内存泄漏的 BUG。
• List 初始化时会实例化一个模板Item缓存起来，并将原有引用的模板Item销毁。所以以后不支持两个List的模板Item引用同一个Node。（Prefab则没有这个限制）;

• 修复使用循环列表+单/多选模式时，选择回调事件的参数可能会超过numItems（或数据数组长度）的 BUG。
• 修复示例项目Main.scene的报错。

示例项目升级至 ccc_v2.2.1。

• 适配cc.Widget。（感谢 Cocos 论坛用户@ckcfcc）
• 新增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 ）。