Skip to content

UICollectionView ​

UICollectionView 表示一个能滚动的列表。它只为屏幕上看得见的那几行创建视图,行滚出屏幕之后,它的视图被拿去显示新滚进来的行。所以几千行的列表和几十行的列表占用的内存差不多。

列表不直接存数据。数据分成两部分交给它:有哪些项、什么顺序放在快照里,快照里只有标识,一项一个;每一项长什么样写在数据源的 cellProvider 函数里,系统要显示某一项时调它,它返回设好内容的单元格。改数据时不用告诉列表「第 3 行删了」:建一份新的快照交给数据源,系统比较前后两份,自己算出哪些行要插入、删除、移动。

和列表一起用的是这一组类:

类是什么
UICollectionView(本页)列表
UICollectionViewDiffableDataSource数据源。列表显示什么,由它决定
NSDiffableDataSourceSnapshot快照。一份「有哪些分区、每个分区里有哪些项」的清单
NSIndexPath一项的位置:第几个分区的第几项
UICollectionReusableView列表里能复用的视图的基类
UICollectionViewCell单元格。一项在屏幕上的视图
UICollectionViewListCell列表布局用的单元格
UIListContentConfiguration一行的内容:主文字、副文字、图片
UICollectionViewLayout布局对象的基类
UICollectionViewCompositionalLayout列表用的布局
UICollectionLayoutListConfiguration列表的外观:圆角卡片、通栏、分隔线

列表是滚动视图:滚动视图的属性和事件它都有。

这一组页面里的行为都在模拟器(iPhone Air,iOS 27.2)的验收用例里验证过,标了「未在模拟器验证」的除外。屏幕上的样子没有逐项核对。

继承关系:EventTarget → NSObject → UIResponder → UIView → UIScrollView → UICollectionView

怎么做一个列表、增删改行、点选、加载更多,见指南做一个列表。

构造函数 ​

UICollectionView()

用一个布局对象创建列表。

实例属性 ​

还继承 UIScrollView 和 UIView 的属性。列表常用的继承属性是 contentOffset、keyboardDismissMode。

属性说明
collectionViewLayout 只读建的时候给的布局对象
dataSource 只读接在它上面的数据源
allowsSelection用户能不能点选
allowsMultipleSelection能不能同时选中多项
numberOfSections 只读现在有几个分区
visibleCells 只读现在在屏幕上的单元格
indexPathsForVisibleItems 只读现在在屏幕上的各项的位置
indexPathsForSelectedItems 只读选中的各项的位置

实例方法 ​

还继承 UIScrollView 和 UIView 的方法。

单元格:

方法说明
registerClass()登记一种单元格
dequeueReusableCellWithReuseIdentifier()在 cellProvider 里取一个单元格
cellForItemAtIndexPath()某一项现在的单元格
indexPathForCell()一个单元格现在显示的是哪一项

查询:

方法说明
numberOfItemsInSection()某个分区里有几项
indexPathForItemAtPoint()一个点落在哪一项上

选中和滚动:

方法说明
selectItemAtIndexPath()选中一项
deselectItemAtIndexPath()取消选中一项
scrollToItemAtIndexPath()滚到某一项

事件 ​

用 addEventListener() 监听。

事件什么时候派发
itemselect用户点选了一项
itemdeselect用户让一项不再选中
beforedisplay一项的单元格即将出现在屏幕上
displayend一项的单元格离开了屏幕
scroll 等滚动视图的八个事件,继承自 UIScrollView,和这四个互不影响

四个事件共同的规则:

  • 事件对象是 UICollectionViewItemEvent,多一个只读字段 indexPath,类型是 NSIndexPath。
  • 不能取消,preventDefault() 不起作用。
  • 回调排在当前这一轮代码之后执行。indexPath 是事件发生那一刻的位置;回调执行前数据变了的话,这个位置上可能已经是另一项,或者没有项。要长期用一项,先用数据源的 itemIdentifierForIndexPath() 换成标识。

标识 ​

标识是 App 给每一项起的名字,用来区分它和别的项。它是字符串或者整数。

  • 同一个快照里,项的标识不能重复,不同分区里的项也不能重复。分区的标识同样不能重复。
  • '1' 和 1 是两个不同的标识。
  • 标识要稳定:同一项在前后两份快照里用同一个标识,系统才知道它是同一项。用订单号、用户 id 这类不会变的值,不要用它在数组里的下标。
  • 系统交回来的标识,类型上是 string | number。按标识取数据时先转成 App 用的那一种,比如 orders.get(String(id))。

分区和项 ​

列表里的内容分两层:分区,和分区里的项。只有一组内容时也要有一个分区。

一项的位置用 NSIndexPath 表示:section 是第几个分区,item 是分区里的第几项,都从 0 数。需要位置的参数可以给 NSIndexPath,也可以给 { section: 0, item: 3 } 这样的普通对象;读出来的都是 NSIndexPath。

位置不是一项的身份。在它前面插一行,它的位置就变了。要长期记住一项,记它的标识。

手里有想要用
位置标识source.itemIdentifierForIndexPath(indexPath)
标识位置source.indexPathForItemIdentifier(id)

单元格的登记和取用 ​

单元格不能用 new 建。分两步:

  1. 建列表之后,用 registerClass() 登记一种单元格,给它一个复用标识。
  2. 在 cellProvider 里用 dequeueReusableCellWithReuseIdentifier() 按这个复用标识取。有能复用的就给复用的,没有就新建。

复用标识和项的标识是两回事。复用标识表示「哪一种单元格」,一个列表通常只有一两种。

单元格是复用的:一项滚出屏幕后,它的单元格不销毁,留着显示别的项。所以 cellProvider 拿到的单元格可能是新的,也可能上面还留着另一项的内容。每次都把单元格上的内容整个设一遍;一项的数据放在 App 自己的 Map 或数组里,按标识取,不要用单元格记数据。

示例 ​

订单列表 ​

从空白 App 开始,显示一个订单列表,点一行在控制台输出订单号,两秒后删掉第一行。

js
application.addEventListener('sceneconnect', (e) => {
  const win = new UIWindow(e.scene);
  const page = new UIViewController();
  page.view.backgroundColor = 'systemBackground';
  win.rootViewController = page;
  win.makeKeyAndVisible();

  const orders = new Map([
    ['A1001', { title: '咖啡豆 500 g', status: '已发货' }],
    ['A1002', { title: '手冲壶', status: '待付款' }],
    ['A1003', { title: '滤纸 100 张', status: '已签收' }],
  ]);

  const list = new UICollectionView(
    UICollectionViewCompositionalLayout.layoutWithListConfiguration(
      new UICollectionLayoutListConfiguration('insetGrouped')));
  list.registerClass(UICollectionViewListCell, { forCellWithReuseIdentifier: 'row' });

  const source = new UICollectionViewDiffableDataSource(list, {
    cellProvider(collectionView, indexPath, id) {
      const cell = collectionView.dequeueReusableCellWithReuseIdentifier(
        'row', { forIndexPath: indexPath });
      const order = orders.get(String(id));
      const content = cell.defaultContentConfiguration();
      content.text = order ? order.title : '';
      content.secondaryText = order ? order.status : '';
      cell.contentConfiguration = content;
      return cell;
    },
  });

  const snapshot = new NSDiffableDataSourceSnapshot();
  snapshot.appendSectionsWithIdentifiers(['main']);
  snapshot.appendItemsWithIdentifiers(Array.from(orders.keys()));
  source.applySnapshot(snapshot, { animatingDifferences: false });

  list.addEventListener('itemselect', (event) => {
    console.log('点了 ' + source.itemIdentifierForIndexPath(event.indexPath));
  });

  setTimeout(() => {
    const next = source.snapshot();
    next.deleteItemsWithIdentifiers(['A1001']);
    source.applySnapshot(next);
  }, 2000);

  list.translatesAutoresizingMaskIntoConstraints = false;
  page.view.addSubview(list);
  NSLayoutConstraint.activateConstraints([
    list.topAnchor.constraintEqualToAnchor(page.view.topAnchor),
    list.bottomAnchor.constraintEqualToAnchor(page.view.bottomAnchor),
    list.leadingAnchor.constraintEqualToAnchor(page.view.leadingAnchor),
    list.trailingAnchor.constraintEqualToAnchor(page.view.trailingAnchor),
  ]);
});

效果

  • 屏幕上出现一个圆角卡片,里面三行,每行上面是商品名,下面是灰色的状态。
  • 点一行,这一行变成高亮,控制台输出 点了 A1002。未在模拟器验证:点选只有真实触摸能触发。
  • 两秒后第一行带动画地消失,下面两行移上来。

对应的 iOS API ​

ObjCJS
[[UICollectionView alloc] initWithFrame:CGRectZero collectionViewLayout:layout]new UICollectionView(layout)
[list registerClass:UICollectionViewListCell.class forCellWithReuseIdentifier:@"row"]list.registerClass(UICollectionViewListCell, { forCellWithReuseIdentifier: 'row' })
[list dequeueReusableCellWithReuseIdentifier:@"row" forIndexPath:indexPath]list.dequeueReusableCellWithReuseIdentifier('row', { forIndexPath: indexPath })
[list scrollToItemAtIndexPath:path atScrollPosition:UICollectionViewScrollPositionTop animated:YES]list.scrollToItemAtIndexPath(path, { atScrollPosition: ['top'], animated: true })
collectionView:didSelectItemAtIndexPath:(委托方法)itemselect 事件,位置在 event.indexPath
collectionView:didDeselectItemAtIndexPath:(委托方法)itemdeselect 事件
collectionView:willDisplayCell:forItemAtIndexPath:(委托方法)beforedisplay 事件
collectionView:didEndDisplayingCell:forItemAtIndexPath:(委托方法)displayend 事件

和 ObjC 不一样的地方:

  • 系统对用错的情况(标识重复、位置不存在、在 cellProvider 之外取单元格)是抛出让 App 崩溃的异常,JS 里是可以 catch 的 TypeError。
  • NSNotFound 换成了 -1。
  • 标识在 ObjC 里可以是任何可哈希的对象,JS 里是字符串或整数。

参见 ​