/cocoscreator-list

这是一个基于CocosCreator的List（列表）组件。支持虚拟列表、不定宽/高、选择模式、滑动模式等。

Primary LanguageTypeScript

List

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

Cocos论坛帖子链接：

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

本组件支持：

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

使用说明

  1. 在编辑器中，创建一个ScrollView（也就是ScrollView->Mask->Content这样层级结构的节点！）。
  2. 将 List 组件拖拽到ScrollView节点上。
  3. 设置模板Item，选择 TemplateType ，可切换模板类型，请按需选择。
  4. 设置滑动模式（ SlideMode ）， NORMAL=通常 ， ADHERING=粘附 ， PAGE=分页 ，三选一。
  5. 设置是否为虚拟列表（ Virtual ），默认为 true ，如果为 false ，则跟普通列表没有区别。
  6. 可选设置逐帧渲染（ FrameByFrameRenderNum ），该数量为每帧渲染的数量。
  7. 设置渲染器（ RenderEvent ），在View中写一个函数，将该函数指向RenderEvent，运行时，设置List数量，Item将会通过该函数进行回调，开发者在该函数中实现Item的刷新。
  8. 可选设置选择模式（ SelectedMode ），选择模式有 SIMPLE（单选） 、 MULT（多选） 两种模式，须与 ListItem 组件搭配使用， ListItem 组件需要拖拽到模板Item上。在View中写一个函数，将该函数指向 SelectedEvent ，运行时，当选择变更，将会通过该函数回调。

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

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

在View中设置 list.customSize 以达到每个Item宽度或高度不一样的虚拟列表效果，简直美滋滋！但这个会耗费更多性能！仅支持虚拟列表！仅支持单列或单行！

注意

  1. 本组件所依赖的ScrollView节点、Mask节点以及Content节点，这三个节点的锚点需要按方向去设置。比如从顶到底单列排列，就需要设置锚点为（0.5, 1）。如果是从左到右网格排列，就需要设置锚点为（0, 1）。始终将锚点设置到首个Item那一边。
  2. 理论上设为虚拟列表后不可再设回普通列表（即 virtual 属性）。
  3. SlideMode设为 ADHERING（粘附） 或 PAGE（页面） 后，组件将强行屏蔽惯性滚动。

更新日志

2019/7/20

  • 新增 LakeCenter 属性。当该属性为 true ，Item数量过少时，会居中显示所有Item。（不支持 GRID 布局）
  • 新增 calcCustomSize 接口，方便开发者计算 CustomSize 。（如果模板Item的结构较复杂，建议还是在外部自行计算）
  • 修复反方向布局，Item数量过少时，会向正方向对齐的BUG。

2019/6/15

  • 滑动模式新增 PAGE 模式，用来做分页效果，可自定义翻页滑动响应距离（ pageDistance ）。建议不要再用 ADHERING 模式去实现分页效果。关于 PAGE 模式下的接口： list.prePage(timeInSecond) 、 list.nextPage(timeInSecond) 、 list.skipPage(pageNum, timeInSecond) ，分别是上一页、下一页、跳转到指定页数。
  • 优化效率。

2019/6/7

  • 新增TS版本。

2019/5/28

  • 优化效率。

2019/5/27

  • 修复滑动模式为吸附（ADHERING）时，还未吸附到目标点时，点击滚动窗，再松开，会吸附失败的BUG。
  • 独立吸附接口 list.adhere() ，可外部调用，不限滑动模式。

2019/5/23

  • 支持 BOTTOM_TO_TOP ， RIGHT_TO_LEFT 布局。需要注意：各种反方向排列的布局（ BOTTOM_TO_TOP 、 RIGHT_TO_LEFT ）都会有问题（item数量过少，就会导致Content错位），这个是官方问题。而本组件是配合 cc.ScrollView 去写的，所以也不支持，待官方后续优化（Last test by Creator_v2.1.1）。如果Item数量很多，那么可以使用。

2019/5/21

  • 单列布局时支持自定义指定Item的height。单行布局时支持自定义指定Item的width。通过 list.customSize = {0:100, 1:130, 5:120, ...} 来设置，其中key为Item的ID，value为height/width，没有找到该Item的customSize将会与模板ItemSize一致。

2019/5/16

  • 新增List的配套组件---- ListItem 。
  • 新增选择模式。

2019/5/13

  • 新增带动画删除Item接口 list.aniDelItem(id, callFunc, aniType) ，因本组件毕竟还是数据驱动，所以请务必在callFunc中删除数据数组中相应下标的数据，然后手动更新该list（即 list.numItems=Number ）。