Dart/Flutter + Firestore：离线环境下如何获取新增对象ID？

我有一个创建新联系人的表单，包含“创建”按钮。点击按钮时表单进入只读模式，创建成功后跳转到新联系人页面。只读模式功能正常，但离线环境下跳转存在问题。

在线环境可用的创建按钮代码（位于带pending状态的有状态组件内）：

setState(() {
  pending = true;
});
FirebaseFirestore.instance.collection(...).withConverter(...).add(contact).then((addedContact) {
  setState(() {
    pending = false;
  });
  context.goNamed('contact', params: {'contactId' : addedContact.id});
});

离线环境中，集合监听器已能看到新增的联系人，但上述add()的then回调始终不执行。我考虑过手动生成ID、监听集合并在对应ID的对象创建时跳转，想知道这类场景的最佳实践。

补充：测试环境为Web应用，初始化代码如下：

WidgetsFlutterBinding.ensureInitialized();

await Firebase.initializeApp(
  options: DefaultFirebaseOptions.currentPlatform,
);
await FirebaseFirestore.instance.enablePersistence(const PersistenceSettings(synchronizeTabs: true));
await FirebaseFirestore.instance.disableNetwork();

核心原因 #

Firestore的add()方法的then回调仅在服务器确认写入成功后才会触发，离线环境下本地写入完成后不会执行该回调，这就是跳转逻辑失效的根本原因。

最佳实践 #

1. 手动生成文档ID，用set()替代add()

离线场景下，主动生成文档ID是最直接的解决方案：

• 先生成唯一ID：final contactId = FirebaseFirestore.instance.collection('contacts').doc().id;
• 用set()写入数据，而非依赖add()自动生成ID
• 写入本地完成后直接跳转，无需等待服务器响应（因为本地持久化已生效，监听器也能获取到数据）

示例代码：

setState(() => pending = true);
final contactId = FirebaseFirestore.instance.collection('contacts').doc().id;

try {
  await FirebaseFirestore.instance
      .collection('contacts')
      .doc(contactId)
      .withConverter(...).set(contact);
  
  setState(() => pending = false);
  // 直接跳转，无需等待服务器回调
  context.goNamed('contact', params: {'contactId': contactId});
} catch (e) {
  setState(() => pending = false);
  // 处理本地写入失败（比如权限问题、数据格式错误）
}

2. 监听服务器同步状态（可选）

如果需要确认数据最终同步到服务器，可以监听目标文档的元数据：

FirebaseFirestore.instance
    .collection('contacts')
    .doc(contactId)
    .snapshots()
    .listen((snapshot) {
  // hasPendingWrites为false时，说明数据已同步到服务器
  if (!snapshot.metadata.hasPendingWrites && snapshot.exists) {
    // 可在此添加同步完成的提示（比如更新UI状态）
  }
});

3. 保持只读模式的正确性

• 本地写入成功后再关闭pending状态，避免用户重复提交
• 如果本地写入失败（比如持久化存储已满），需重置pending状态并提示用户

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