Skip to content

NSDiffableDataSourceSnapshot ​

NSDiffableDataSourceSnapshot 表示一份列表数据的清单:有哪些分区、每个分区里有哪些项、什么顺序。里面只有标识,没有内容;内容在数据源的 cellProvider 里按标识去取。

快照只是数据,改它不影响屏幕。交给数据源的 applySnapshot() 之后列表才变。

得到快照有两种方式:

方式得到什么什么时候用
new NSDiffableDataSourceSnapshot()空的快照第一次放数据;数据整体换掉
source.snapshot()列表现在的数据的一份副本在现有数据上增、删、改

继承关系:EventTarget → NSObject → NSDiffableDataSourceSnapshot

构造函数 ​

NSDiffableDataSourceSnapshot()

建一份空的快照。

实例属性 ​

属性说明
numberOfSections 只读一共有几个分区
numberOfItems 只读一共有几项
sectionIdentifiers 只读全部分区的标识,按顺序
itemIdentifiers 只读全部项的标识,按分区的顺序接在一起

实例方法 ​

查询:

方法说明
numberOfItemsInSection()一个分区里有几项
itemIdentifiersInSectionWithIdentifier()一个分区里各项的标识
sectionIdentifierForSectionContainingItemIdentifier()一项在哪个分区
indexOfItemIdentifier()一项在全部项里排第几
indexOfSectionIdentifier()一个分区排第几

改分区:

方法说明
appendSectionsWithIdentifiers()在最后加几个分区
insertSectionsWithIdentifiers()插在某个分区的前面或后面
deleteSectionsWithIdentifiers()删掉几个分区和里面的项
moveSectionWithIdentifier()把一个分区移到另一个的前面或后面
reloadSectionsWithIdentifiers()标记几个分区里的项内容变了

改项:

方法说明
appendItemsWithIdentifiers()加到一个分区的末尾
insertItemsWithIdentifiers()插在某一项的前面或后面
deleteItemsWithIdentifiers()删掉几项
deleteAllItems()删掉全部分区和项
moveItemWithIdentifier()把一项移到另一项的前面或后面
reloadItemsWithIdentifiers()标记几项内容变了,应用时换一个单元格
reconfigureItemsWithIdentifiers()标记几项内容变了,应用时用原来的单元格

改动方法的共同规则 ​

  • 都没有返回值。要传一组标识的参数都是数组。
  • 带 before… 和 after… 两个键的方法,两个键必须给一个,而且只给一个。
  • 出错时都抛 TypeError,报错开头是方法名。出错时快照保持原样,那一次调用里的标识一个都不会加进去。
情况报错
标识不是字符串或整数appendItemsWithIdentifiers: identifiers must be strings or integers, got 1.5
该给数组的地方不是数组appendItemsWithIdentifiers needs an array of identifiers
要加的标识已经在快照里appendItemsWithIdentifiers: item identifier "pear" is already in the snapshot
同一次调用里标识重复appendItemsWithIdentifiers: item identifier "x" appears more than once
指的分区不存在appendItemsWithIdentifiers: there is no section with identifier "nope"
指的项不存在(插入的位置、移动、重新加载、重新设置)insertItemsWithIdentifiers: there is no item with identifier "nope"
before… 和 after… 没给或者都给了insertItemsWithIdentifiers needs exactly one of { beforeItemWithIdentifier } or { afterItemWithIdentifier }

内容变了:reload 和 reconfigure ​

reloadItemsWithIdentifiers() 和 reconfigureItemsWithIdentifiers() 都表示「这一项的内容变了」,区别在单元格:

方法应用快照时
reconfigureItemsWithIdentifiers()在原来的单元格上再调一次 cellProvider。一般用这个
reloadItemsWithIdentifiers()换一个单元格,再调 cellProvider

只改 App 自己存的数据,列表不会变:快照里只有标识,标识没变,系统就认为没有东西要更新。

示例 ​

两个分区 ​

js
const snapshot = new NSDiffableDataSourceSnapshot();
snapshot.appendSectionsWithIdentifiers(['unpaid', 'done']);
snapshot.appendItemsWithIdentifiers(['A1002'], { intoSectionWithIdentifier: 'unpaid' });
snapshot.appendItemsWithIdentifiers(['A1001', 'A1003'], { intoSectionWithIdentifier: 'done' });
console.log(snapshot.numberOfSections, snapshot.numberOfItems, snapshot.itemIdentifiers.join(','));

结果:输出 2 3 A1002,A1001,A1003。

对应的 iOS API ​

ObjCJS
[[NSDiffableDataSourceSnapshot alloc] init]new NSDiffableDataSourceSnapshot()
[snapshot appendItemsWithIdentifiers:ids intoSectionWithIdentifier:@"main"]snapshot.appendItemsWithIdentifiers(ids, { intoSectionWithIdentifier: 'main' })
[snapshot insertItemsWithIdentifiers:ids beforeItemWithIdentifier:@"x"]snapshot.insertItemsWithIdentifiers(ids, { beforeItemWithIdentifier: 'x' })

标识在 ObjC 里可以是任何可哈希的对象,JS 里是字符串或整数。NSNotFound 换成了 -1。系统对用错的情况抛出让 App 崩溃的异常,JS 里是可以 catch 的 TypeError。

参见 ​