如何监听Firestore连接状态变化，以便及时提示用户数据时效性？

为什么fromCache不能准确判断离线状态 #

在线状态下执行写入操作时，Firestore客户端会优先把变更应用到本地缓存，立刻触发监听器并返回fromCache = true的结果，同时在后台异步将变更同步到云端。这种设计是为了减少用户操作的延迟，但会导致fromCache无法准确反映当前的网络连接状态——此时明明在线，却会被误判为离线。

正确的连接状态监听方法 #

Firestore提供了专门的API来监听连接状态，通过监听包含元数据变化的快照，结合两个元数据字段判断：

Web（v9+）实现 #

import { getFirestore, onSnapshot } from "firebase/firestore";

const db = getFirestore();

// 开启元数据变化监听
const unsubscribe = onSnapshot(db, { includeMetadataChanges: true }, (snapshot) => {
  const isConnected = !snapshot.metadata.fromCache && !snapshot.metadata.hasPendingWrites;
  
  if (!isConnected) {
    // 显示离线提示："当前处于离线状态，数据可能并非最新"
    console.log("当前处于离线状态，数据可能并非最新");
  } else {
    // 隐藏提示，恢复正常状态
    console.log("已连接云端，数据为最新版本");
  }
});

// 页面卸载或不再需要监听时取消
// unsubscribe();

Android实现 #

val db = Firebase.firestore
db.addSnapshotListener(MetadataChanges.INCLUDE) { snapshot, error ->
    error?.let {
        // 处理监听错误
        return@addSnapshotListener
    }

    val isConnected = !snapshot!!.metadata.isFromCache && !snapshot.metadata.hasPendingWrites
    if (!isConnected) {
        Toast.makeText(context, "当前处于离线状态，数据可能并非最新", Toast.LENGTH_SHORT).show()
    }
}

iOS实现 #

import FirebaseFirestore

let db = Firestore.firestore()
let listener = db.addSnapshotListener(includeMetadataChanges: true) { snapshot, error in
    guard let snapshot = snapshot else {
        // 处理错误
        return
    }

    let isConnected = !snapshot.metadata.isFromCache && !snapshot.metadata.hasPendingWrites
    if !isConnected {
        print("当前处于离线状态，数据可能并非最新")
        // 这里可以更新UI显示提示
    }
}

// 取消监听时调用
// listener.remove()

判断逻辑说明 #

• !snapshot.metadata.fromCache：确保数据来自云端而非本地缓存
• !snapshot.metadata.hasPendingWrites：确保没有待同步到云端的本地修改

当两个条件同时满足时，说明客户端在线且数据已完全同步；只要有一个不满足，就说明当前可能处于离线状态或正在同步数据，此时可以向用户展示提示信息。

内容的提问来源于stack exchange，提问作者Anakhand