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
怎么做一个列表、增删改行、点选、加载更多,见指南做一个列表。
构造函数
用一个布局对象创建列表。
实例属性
还继承 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 建。分两步:
- 建列表之后,用
registerClass()登记一种单元格,给它一个复用标识。 - 在
cellProvider里用dequeueReusableCellWithReuseIdentifier()按这个复用标识取。有能复用的就给复用的,没有就新建。
复用标识和项的标识是两回事。复用标识表示「哪一种单元格」,一个列表通常只有一两种。
单元格是复用的:一项滚出屏幕后,它的单元格不销毁,留着显示别的项。所以 cellProvider 拿到的单元格可能是新的,也可能上面还留着另一项的内容。每次都把单元格上的内容整个设一遍;一项的数据放在 App 自己的 Map 或数组里,按标识取,不要用单元格记数据。
示例
订单列表
从空白 App 开始,显示一个订单列表,点一行在控制台输出订单号,两秒后删掉第一行。
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
| ObjC | JS |
|---|---|
[[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 里是字符串或整数。
参见
- 做一个列表:增删改行、分区、点选、滚动、加载更多、自己的视图
UIScrollView:列表继承的滚动属性和事件UICollectionViewDiffableDataSource、NSDiffableDataSourceSnapshot:给列表数据UICollectionViewListCell、UIListContentConfiguration:一行显示什么application:cellProvider出错时的error事件