Flutter中如何判断Firestore文档是本地缓存还是已同步至云端？

我正在给一款开源Flutter聊天APP实现消息保存确认功能，要判断消息是否已经成功保存到Firestore云端数据库。目前的实现方式是通过云函数，在消息文档创建后自动添加sentAt字段，然后通过监听receivingMessagesStream获取带有非空sentAt的消息版本，以此来标记消息已同步到云端。现在想知道有没有其他方案，可以直接判断Firestore文档是仅存在于本地设备，还是已经同步到云端？

当前实现代码 #

Flutter端监听代码 #

final receivingMessagesStream = firestore
        .collection("conversations")
        .doc(conversationId)
        .collection("messages")
        .snapshots()

Firebase云函数代码 #

import * as logger from "firebase-functions/logger";
import {onDocumentCreated} from "firebase-functions/v2/firestore";
import * as admin from "firebase-admin";

exports.sentAtTrigger = onDocumentCreated("conversations/{conversationId}/messages/{messageId}", async (event) => {
    logger.log(`new message created: ${event.data!.id}`);
    await event.data!.ref.update({
        sentAt: admin.firestore.FieldValue.serverTimestamp()
    });
});

• 利用Firestore的hasPendingWrites属性
  Firestore的DocumentSnapshot对象自带hasPendingWrites属性，返回true表示文档仅存在本地修改、未同步到云端；返回false则说明修改已同步完成。无需额外云函数，直接在客户端监听时判断：

  receivingMessagesStream.listen((snapshot) {
    for (var docChange in snapshot.docChanges) {
      final messageDoc = docChange.doc;
      final isSynced = !messageDoc.metadata.hasPendingWrites;
      // 根据isSynced更新消息的已保存状态
    }
  });
  

• 客户端本地标记 + 写入回调确认
  发送消息时给本地新增文档添加临时字段（如isLocalOnly: true），待Firestore写入完成的Future回调触发后，移除该标记：

  // 发送消息时标记为本地仅存
  final newMessageRef = firestore
      .collection("conversations")
      .doc(conversationId)
      .collection("messages")
      .doc();
  
  await newMessageRef.set({
    "content": messageContent,
    "isLocalOnly": true,
    "createdAt": FieldValue.serverTimestamp()
  });
  
  // 写入云端完成后移除本地标记
  await newMessageRef.update({"isLocalOnly": FieldValue.delete()});
  

  监听快照时，若文档无isLocalOnly字段，即可判定已同步到云端。

• 组合hasPendingWrites与fromCache属性
  fromCache属性表示快照数据是否来自本地缓存，结合hasPendingWrites可更精准判断同步状态：

  final isSynced = !messageDoc.metadata.hasPendingWrites && !messageDoc.metadata.fromCache;
  

  该判断可确认文档已完全同步到云端，且当前快照为云端最新数据。

内容的提问来源于stack exchange，提问作者Rodrigo João Bertotti