启用离线功能

即使网络连接暂时中断，Firebase 应用仍可正常工作。此外，Firebase 还提供用于在本地持久保存数据、管理在线状态和应对延迟的工具。

磁盘持久化

Firebase 应用会自动处理临时性网络中断。 缓存的数据在离线状态下依然可用，而且 Firebase 会在网络连接恢复后重新发送所有中断期间的写入操作。

启用磁盘持久化后，您的应用会通过本地写入将数据保存到设备上，以便在离线时保存状态数据。即使用户或操作系统重启应用，这些数据也不会丢失。

只需一行代码便可启用磁盘持久化。

FirebaseDatabase.instance.setPersistenceEnabled(true);

持久化行为

启用持久化后，Firebase Realtime Database 客户端在线期间会同步的所有数据都会持久保存在磁盘中，可供离线时使用。即使用户或操作系统重启应用，这些数据也不会丢失。也就是说，您的应用会使用存储在缓存中的本地数据，如同在线时一样正常运行。本地更新仍会触发监听器回调。

Firebase Realtime Database 客户端会自动将应用在离线状态下执行的所有写入操作维护到一个队列中。启用持久化后，这个队列也会持久保存在磁盘中，这样，当用户或操作系统重启应用后，所有写入操作都不会丢失。当应用恢复连接时，所有操作都将发送到 Firebase Realtime Database 服务器。

如果应用使用 Firebase Authentication，Firebase Realtime Database 客户端还会持久保留用户的身份验证令牌，即使应用重启也不受影响。如果身份验证令牌在应用处于离线状态时到期，则客户端会暂停写入操作，直到应用重新进行身份验证，否则写入操作可能会由于安全规则而失败。

及时更新数据

Firebase Realtime Database 会同步数据并存储一份本地副本，以供处于活跃状态的监听器使用。此外，您还可以使特定位置中的数据保持同步。

final scoresRef = FirebaseDatabase.instance.ref("scores");
scoresRef.keepSynced(true);

Firebase Realtime Database 客户端会自动下载这些位置中的数据并使其保持同步，即使引用中没有处于活跃状态的监听器也是如此。您可以使用下面这行代码停用同步。

scoresRef.keepSynced(false);

默认情况下，之前同步的数据中有 10 MB 会被写入缓存。这对大多数应用来说应该足够了。如果缓存数据的大小超过其配置的大小，Firebase Realtime Database 会清除最久未使用的数据。保持同步的数据不会从缓存中清除。

离线查询数据

Firebase Realtime Database 会存储查询所返回的数据，供离线状态下使用。对于在离线状态下构建的查询，Firebase Realtime Database 会继续使用之前加载的数据。如果请求的数据还未加载，Firebase Realtime Database 会从本地缓存中加载数据。在恢复网络连接后，应用会加载数据并给出查询结果。

例如，以下代码会查询 scores 数据库中的最后四条记录：

final scoresRef = FirebaseDatabase.instance.ref("scores");
scoresRef.orderByValue().limitToLast(4).onChildAdded.listen((event) {
  debugPrint("The ${event.snapshot.key} dinosaur's score is ${event.snapshot.value}.");
});

假设用户连接中断，进入离线状态，然后重启了应用。应用在离线状态下从同一位置查询最后两条记录。此查询会成功返回最后两条记录，因为应用已经加载过上述查询中的所有四条记录。

scoresRef.orderByValue().limitToLast(2).onChildAdded.listen((event) {
  debugPrint("The ${event.snapshot.key} dinosaur's score is ${event.snapshot.value}.");
});

在上面的示例中，Firebase Realtime Database 客户端通过使用持久化缓存，针对“分数最高的两种恐龙”查询引发了“child added”事件。但它不会引发“value”事件，因为该应用在处于在线状态时未执行过该查询。

如果在离线状态下查询过最后六条记录，则应用会立即针对已缓存的四条记录引发“child added”事件。设备恢复在线状态后，Firebase Realtime Database 客户端会与服务器同步，并为应用获取最后两个“child added”事件以及“value”事件。

离线处理事务

应用处于离线状态时所执行的所有事务会被放入队列中。 当应用恢复在线状态后，事务将被发送到 Realtime Database 服务器。

注意：事务不会在应用重启后持久保存。即使启用了持久化，事务也不会在应用重启后持久保存。因此，您不能指望离线时所执行的事务会提交到您的 Firebase Realtime Database。为提供最佳的用户体验，您的应用应指出事务尚未保存到 Firebase Realtime Database 中，或者您应确保您的应用支持手动记住事务并在应用重启后重新执行这些事务。

Firebase Realtime Database 提供多项功能，用于处理离线情形和各种网络连接状况。无论您是否为应用启用磁盘持久化，本指南的其余部分都适用于您的应用。

管理在线状态

在实时应用中，通常需要检测客户端何时建立和断开连接。例如，当用户的客户端断开连接时，您可能需要将该用户标记为“离线”。

Firebase Database 客户端提供了一些简单的原语，在某个客户端与 Firebase Database 服务器断开连接时，可以使用这些原语向数据库写入数据。这些更新的完成情况与客户端是否正常断开连接无关，因此，即使连接突然中断或客户端崩溃，您仍可以依靠此类更新来清理数据。所有写入操作（包括设置、更新和移除）均可以在断开连接时执行。

在下面这个简单的示例中，我们使用 onDisconnect 原语在断开连接时写入数据：

final presenceRef = FirebaseDatabase.instance.ref("disconnectmessage");
// Write a string when this client loses connection
presenceRef.onDisconnect().set("I disconnected!");

onDisconnect 的工作方式

当您建立 onDisconnect() 操作后，该操作会在 Firebase Realtime Database 服务器上驻留。该服务器会检查安全性，确保用户可以执行所请求的写入事件，并在该操作无效时通知您的应用。然后，服务器会监控连接状况。如果连接超时，或 Realtime Database 客户端主动关闭连接，服务器会再一次检查安全性（以确保操作仍有效），然后触发事件。

try {
    await presenceRef.onDisconnect().remove();
} catch (error) {
    debugPrint("Could not establish onDisconnect event: $error");
}

您还可以调用 .cancel() 来取消 onDisconnect 事件：

final onDisconnectRef = presenceRef.onDisconnect();
onDisconnectRef.set("I disconnected");
// ...
// some time later when we change our minds
// ...
onDisconnectRef.cancel();

检测连接状态

对于许多与在线状态相关的功能，让您的应用了解自己处于在线还是离线状态非常有用。Firebase Realtime Database 提供了 /.info/connected 这个特殊位置，每当 Firebase Realtime Database 客户端的连接状态发生变化时，该位置都会更新。示例如下：

final connectedRef = FirebaseDatabase.instance.ref(".info/connected");
connectedRef.onValue.listen((event) {
  final connected = event.snapshot.value as bool? ?? false;
  if (connected) {
    debugPrint("Connected.");
  } else {
    debugPrint("Not connected.");
  }
});

/.info/connected 布尔值不会在 Realtime Database 客户端之间同步，因为该值取决于客户端的状态。换句话说，一个客户端的 /.info/connected 值为 false，并不代表另一个客户端的这个值也是 false。

应对延迟

服务器时间戳

Firebase Realtime Database 服务器提供了一种机制，用于以数据形式插入服务器上生成的时间戳。这项功能与 onDisconnect 相结合，可让您轻松准确地记录 Realtime Database 客户端断开连接的时间：

final userLastOnlineRef =
    FirebaseDatabase.instance.ref("users/joe/lastOnline");
userLastOnlineRef.onDisconnect().set(ServerValue.timestamp);

时钟偏差

虽然 ServerValue.timestamp 要准确得多，对大多数读写操作来说也更合适，但有时估算客户端相对于 Firebase Realtime Database 服务器的时钟偏差也很有用。您可以在 /.info/serverTimeOffset 这个位置附加回调函数来获取相应值（以毫秒为单位）。Firebase Realtime Database 客户端会将这个值与本地报告的时间（以毫秒为单位的纪元时间）相加，来估算服务器时间。请注意，这个时间差的准确性可能会受到网络延迟的影响，因此，它主要用于发现较大（> 1 秒）的时钟偏差。

final offsetRef = FirebaseDatabase.instance.ref(".info/serverTimeOffset");
offsetRef.onValue.listen((event) {
  final offset = event.snapshot.value as num? ?? 0.0;
  final estimatedServerTimeMs =
      DateTime.now().millisecondsSinceEpoch + offset;
});

在线状态应用示例

通过将断开连接操作、连接状态监控与服务器时间戳相结合，您可以构建一个用户在线状态系统。在这个系统中，每位用户都可以在数据库中的某个位置存储数据，来表明其 Realtime Database 客户端是否在线。客户端会在处于在线状态时将这个位置设为 true，并在断开连接时将其设置为时间戳。这个时间戳即代表该用户最后的在线时间。

请注意，在将用户标记为在线之前，您的应用应将断开连接操作加入队列，以免在因客户端网络连接中断而无法将两条命令都发送到服务器的情况下，出现竞态条件。

// Since I can connect from multiple devices, we store each connection
// instance separately any time that connectionsRef's value is null (i.e.
// has no children) I am offline.
final myConnectionsRef =
    FirebaseDatabase.instance.ref("users/joe/connections");

// Stores the timestamp of my last disconnect (the last time I was seen online)
final lastOnlineRef =
    FirebaseDatabase.instance.ref("/users/joe/lastOnline");

final connectedRef = FirebaseDatabase.instance.ref(".info/connected");
connectedRef.onValue.listen((event) {
  final connected = event.snapshot.value as bool? ?? false;
  if (connected) {
    final con = myConnectionsRef.push();

    // When this device disconnects, remove it.
    con.onDisconnect().remove();

    // When I disconnect, update the last time I was seen online.
    lastOnlineRef.onDisconnect().set(ServerValue.timestamp);

    // Add this device to my connections list.
    // This value could contain info about the device or a timestamp too.
    con.set(true);
  }
});