Flutter中如何在Firestore的map字段内存储包含"."的内容？

问题原因 #

Firestore 执行 update 操作时，字符串形式的字段路径会自动将 . 识别为嵌套字段的分隔符，因此包含 . 的邮箱地址会被拆分为多层子 map。手动转义 . 无法被 Firestore 识别为普通字符，反而会把转义符也当成键名的一部分，导致结果不符合预期。

方案1：使用 FieldPath 构造字段路径（官方推荐） #

FieldPath 可以将包含特殊字符的字符串完整识别为单个字段名，不会触发分层解析，代码示例如下：

await FirebaseFirestore.instance
    .collection('polls')
    .doc(pollId)
    .update(
      FieldPath(['voteData', currentUser]), 
      option
    );

将voteData和邮箱地址作为数组传入FieldPath，就会被识别为voteData下的对应键，不会拆分邮箱里的.。

方案2：全量更新 voteData 字段 #

先读取当前voteData的内容，修改后合并更新到文档，也可以避免字段路径解析问题：

final docRef = FirebaseFirestore.instance.collection('polls').doc(pollId);
final docSnapshot = await docRef.get();
final currentVoteData = docSnapshot.data()?['voteData'] as Map? ?? {};
// 直接修改map，不需要处理特殊字符
currentVoteData[currentUser] = option;
// 合并更新voteData字段
await docRef.update({'voteData': currentVoteData});

可选替代方案：替换特殊字符 #

如果不想处理字段路径问题，也可以在存储前将邮箱中的.替换为下划线_等无特殊含义的字符，读取时再还原即可：

// 存储时替换
final safeEmail = currentUser.replaceAll('.', '_');
await FirebaseFirestore.instance
    .collection('polls')
    .doc(pollId)
    .update({"voteData.$safeEmail": option});

// 读取时还原
final originalEmail = safeEmail.replaceAll('_', '.');

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