响应变更 - Flutter SDK

在此页面上

关于本页中的示例

注册监听器
注册查询变更监听器
注册 RealmObject 变更监听器
注册集合变更监听器
注册用户实例变更侦听器
暂停和恢复变更监听器
取消订阅变更侦听器
变更通知限制

Atlas Device SDK 已弃用。有关详细信息，请参阅弃用页面。

所有Flutter SDK对象都是活动对象，这意味着它们在修改时会自动更新。每当任何属性发生更改时，SDK 都会发出通知事件。

当用户向列表添加新项目时，您可能希望更新用户界面、显示通知或日志消息。当有人更新该项目时，您可能希望更改其视觉状态或发出网络请求。最后，当有人删除该项目时，您可能希望删除其从用户界面中删除。 SDK 的通知系统允许您监视数据更改并做出React ，而与导致更改的写入无关。

您可以订阅以下事件的变更：

集合查询
Realm 对象
Realm 对象中的集合
用户实例

关于本页中的示例

本页中的示例使用两种对象类型：、 Character和Fellowship ：

@RealmModel()
class _Character {
  @PrimaryKey()
  late ObjectId id;
  late String name;
  late String species;
  late int age;
}
@RealmModel()
class _Fellowship {
  @PrimaryKey()
  late ObjectId id;
  late String name;
  late List<_Character> members;
}

此外，这些示例还包含以下示例数据：

final frodo = Character(ObjectId(), 'Frodo', 'Hobbit', 51);
final samwise = Character(ObjectId(), 'Samwise', 'Hobbit', 39);
final gollum = Character(ObjectId(), 'Gollum', 'Hobbit', 589);
final aragorn = Character(ObjectId(), 'Aragorn', 'Human', 87);
final legolas = Character(ObjectId(), 'Legolas', 'Elf', 2931);
final gimli = Character(ObjectId(), 'Gimli', 'Dwarf', 140);
final fellowshipOfTheRing = Fellowship(
    ObjectId(), 'Fellowship of the Ring',
    members: [frodo, samwise, aragorn, legolas, gimli]);
final config = Configuration.local([Fellowship.schema, Character.schema]);
final realm = Realm(config);
realm.write(() {
  realm.add(fellowshipOfTheRing);
  realm.add(gollum); // not in fellowship
});

注册监听器

注册查询变更监听器

您可以为Realm中的任何查询注册通知处理程序。处理程序接收 RealmResultsChanges 对象，其中包括自上次通知以来变更的描述。RealmResultsChanges 包含以下属性：

属性	类型	说明
`inserted`	列表<int>	此版本中添加的新集合的索引。
`modified`	列表<int>	此版本中修改的新集合中对象的索引。
`deleted`	列表<int>	先前版本的集合索引已从本版本中删除。
`newModified`	列表<int>	考虑删除和插入后已修改对象的索引。
`moved`	列表<int>	集合中移动的对象的索引。
`results`	RealmResults<T 作为 RealmObject>	正受到变更监控的结果集合。
`isCleared`	bool	如果通知回调中的结果集合为空，则返回`true` 。

// Listen for changes on whole collection
final characters = realm.all<Character>();
final subscription = characters.changes.listen((changes) {
  changes.inserted; // Indexes of inserted objects.
  changes.modified; // Indexes of modified objects.
  changes.deleted; // Indexes of deleted objects.
  changes.newModified; // Indexes of modified objects after accounting for deletions & insertions.
  changes.moved; // Indexes of moved objects.
  changes.results; // The full List of objects.
  changes.isCleared; // `true` after call to characters.clear(); otherwise, `false`.
});
// Listen for changes on RealmResults.
final hobbits = fellowshipOfTheRing.members.query('species == "Hobbit"');
final hobbitsSubscription = hobbits.changes.listen((changes) {
  // ... all the same data as above
});

注册 RealmObject 变更监听器

您可以在域中的特定对象上注册通知处理程序。当对象的任何属性发生变化时， Realm会通知您的处理程序。处理程序接收 RealmObjectChanges 对象，其中包括自上次通知以来变更的描述。RealmObjectChanges包含以下属性：

属性	类型	说明
`isDeleted`	bool	`true` 如果对象已被删除。
`object`	RealmObject	正在监控 Realm 对象的更改。
`properties`	列表<String>	已更改的 Realm 对象属性的名称。

final frodoSubscription = frodo.changes.listen((changes) {
  changes.isDeleted; // If the object has been deleted.
  changes.object; // The RealmObject being listened to, `frodo`.
  changes.properties; // The changed properties.
});

注册集合变更监听器

在 1.7.0 版中更改：添加了对 RealmMap 更改侦听器的支持。

在版本2.0.0中进行了更改：向集合侦听器添加了isCollectionDeleted属性。将isCleared属性添加到RealmMapChanges中。

您可以在其他 RealmObject 中的任何支持数据类型的集合上注册通知处理程序。当集合中的任何列项发生变更时，Realm 会通知处理程序。处理程序接收以下对象之一，其中包含自上次通知以来的变更说明：

RealmListChanges 的对象RealmList
RealmSetChanges 的对象RealmSet
RealmMapChanges 的对象RealmMap

RealmListChanges 包含以下属性：

属性	类型	说明
`inserted`	列表<int>	此版本中添加的列表项索引。
`modified`	列表<int>	在列表的先前版本中存在但在此版本中修改的项目的索引。
`deleted`	列表<int>	在列表的先前版本中存在但从此版本中删除的项目的索引。
`newModified`	列表<int>	在考虑删除和插入后已修改项目的索引。
`moved`	列表<int>	在此版本中发生移动的列表项的索引。
`list`	RealmList<T>	`RealmList` 正受到监控，以了解其更改。
`isCleared`	布尔	`true` 当通过调用 RealmList.clear() 清除列表时方法。
`isCollectionDeleted`	布尔	`true` 当包含该列表的父对象已被删除时。

RealmSetChanges 包含以下属性：

属性	类型	说明
`inserted`	列表<int>	此版本中添加的设立中项目的索引。
`modified`	列表<int>	在此版本中修改的项目集先前版本中的项目的索引。
`deleted`	列表<int>	在此版本中删除的先前版本设立的项目的索引。
`newModified`	列表<int>	在考虑删除和插入后已修改项目的索引。
`moved`	列表<int>	在此版本中移动的设立中项目的索引。
`set`	RealmSet<T>	`RealmSet` 正受到监控，以了解其更改。
`isCleared`	布尔	`true` 当通过调用其 RealmSet.clear() 清除设立时方法。
`isCollectionDeleted`	布尔	`true` 当包含该设立的父对象已被删除时。

RealmMapChanges 包含以下属性：

属性	类型	说明
`inserted`	列表<String>	此版本中添加的地图键。
`modified`	列表<String>	先前版本映射的键，其对应值在此版本中被修改。
`deleted`	列表<String>	从此版本中删除的上一版本地图的键。
`map`	RealmMap<T>	`RealmMap` 正受到监控，以了解其更改。
`isCleared`	布尔	`true` 通过调用 RealmMap.clear() 清除地图时方法。
`isCollectionDeleted`	布尔	`true` 当包含地图的父对象已被删除时。

final fellowshipSubscription =
    fellowshipOfTheRing.members.changes.listen((changes) {
  changes.inserted; // Indexes of inserted objects.
  changes.modified; // Indexes of modified objects.
  changes.deleted; // Indexes of deleted objects.
  changes.newModified; // Indexes of modified objects after accounting for deletions & insertions.
  changes.moved; // Indexes of moved objects.
  changes.list; // The full RealmList of objects.
  changes.isCleared; // `true` after call to fellowshipOfTheRing.members.clear(); otherwise, `false`.
  changes.isCollectionDeleted; // `true` if the collection is deleted; otherwise, `false`.
});

注册用户实例变更侦听器

1.9.0 版本中的新增功能。

在Flutter SDK版本1.9.0及更高版本中，您可以在域中的特定User实例上注册通知处理程序。当用户的任何属性发生变化时（示例，用户访问令牌更新或用户状态更改）， Realm会通知您的处理程序。处理程序接收 UserChanges 对象，其中包括自上次通知以来变更的描述。UserChanges包含以下属性：

属性	类型	说明
`user`	user	已更改的用户实例。

final userSubscription = user.changes.listen((changes) {
  changes.user; // the User being listened to
});

暂停和恢复变更监听器

如果暂时不想收到通知，请暂停订阅。您可以稍后继续监听。

subscription.pause();
// The changes.listen() method won't fire until subscription is resumed.
subscription.resume();

取消订阅变更侦听器

当您不想再接收变更监听器所监视数据的更新通知时，请取消对该监听器的订阅。

await subscription.cancel();

变更通知限制

嵌套文档中深度超过四级的变更不会触发变更通知。

如果您的数据结构需要侦听第五层深度或更深层的更改，解决方法包括：

重构模式以减少嵌套。
添加“推送以刷新”一类的内容，使用户能够手动刷新数据。

后退

删除

来年

冻结数据