Flutter中DocumentSnapshotPlatform字段不存在错误及大小写不敏感搜索问题

一、修复StateError字段不存在错误 #

错误原因 #

直接通过DocumentSnapshot[key]访问Firestore文档字段时，若目标字段不存在会抛出StateError。当前代码中(snapshot.data! as dynamic).docs[index]['photoUrl']和['username']的写法存在这个风险。

修复方案 #

使用DocumentSnapshot.get()方法，该方法支持设置默认值，避免字段缺失时触发异常：

// 替换原ListTile中的代码
leading: CircleAvatar(
  backgroundImage: NetworkImage(
    (snapshot.data! as QuerySnapshot).docs[index].get('photoUrl', defaultValue: 'https://via.placeholder.com/150'),
  ),
),
title: Text(
  (snapshot.data! as QuerySnapshot).docs[index].get('username', defaultValue: 'Unknown User'),
),

也可以先检查字段是否存在再取值：

final doc = (snapshot.data! as QuerySnapshot).docs[index];
final photoUrl = (doc.data() as Map).containsKey('photoUrl') ? doc['photoUrl'] : '默认图片URL';
final username = (doc.data() as Map).containsKey('username') ? doc['username'] : 'Unknown User';

二、实现不区分大小写的用户名搜索 #

方案选择 #

推荐在Firestore用户文档中新增usernameLower字段（存储用户名的小写版本），并为该字段创建索引，查询效率更高。如果无法修改数据库，可通过字符串转换实现近似的不区分大小写搜索。

代码修改 #

1. 数据库优化方案（推荐）

   • 存储用户数据时，同步保存usernameLower: username.toLowerCase()
   • 修改查询逻辑：

   future: FirebaseFirestore.instance
       .collection('users')
       .where(
         'usernameLower',
         isGreaterThanOrEqualTo: searchCon.text.toLowerCase(),
         isLessThanOrEqualTo: searchCon.text.toLowerCase() + '\uf8ff',
       )
       .get(),
   

2. 无需修改数据库的方案
   通过转换搜索文本并利用Firestore的字符串范围查询：

   final searchTextLower = searchCon.text.toLowerCase();
   future: FirebaseFirestore.instance
       .collection('users')
       .where(
         'username',
         isGreaterThanOrEqualTo: searchTextLower,
         isLessThanOrEqualTo: searchTextLower + '\uf8ff',
       )
       .get(),
   

   注：该方案依赖Firestore的Unicode字符串排序，能覆盖大部分场景，但无法处理特殊字符的大小写转换问题，可靠性不如数据库存储小写字段。

完整修改后的代码 #

import 'package:cloud_firestore/cloud_firestore.dart';
import 'package:flutter/material.dart';
import 'package:flutter_staggered_grid_view/flutter_staggered_grid_view.dart';
import 'package:insta/utils/colors.dart';

class SearchScreen extends StatefulWidget {
  const SearchScreen({super.key});

  @override
  State<SearchScreen> createState() => _SearchScreenState();
}

class _SearchScreenState extends State<SearchScreen> {
  final TextEditingController searchCon = TextEditingController();
  bool isShowUsers = false;

  @override
  void dispose() {
    searchCon.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: mobileBackgroundColor,
        title: TextFormField(
          controller: searchCon,
          decoration: const InputDecoration(
            labelText: "Search for a user",
          ),
          onChanged: (value) {
            setState(() {
              isShowUsers = value.isNotEmpty; // 优化：输入为空时不显示用户列表
            });
          },
        ),
      ),
      body: isShowUsers
          ? FutureBuilder(
              future: FirebaseFirestore.instance
                  .collection('users')
                  .where(
                    'usernameLower', // 使用存储的小写用户名字段
                    isGreaterThanOrEqualTo: searchCon.text.toLowerCase(),
                    isLessThanOrEqualTo: searchCon.text.toLowerCase() + '\uf8ff',
                  )
                  .get(),
              builder: (context, snapshot) {
                if (snapshot.connectionState == ConnectionState.waiting) {
                  return const Center(child: CircularProgressIndicator());
                }
                if (!snapshot.hasData || snapshot.data!.docs.isEmpty) {
                  return const Center(child: Text("No users found"));
                }
                return ListView.builder(
                  itemCount: snapshot.data!.docs.length,
                  itemBuilder: (context, index) {
                    final doc = snapshot.data!.docs[index];
                    return ListTile(
                      leading: CircleAvatar(
                        backgroundImage: NetworkImage(
                          doc.get('photoUrl', defaultValue: 'https://via.placeholder.com/150'),
                        ),
                      ),
                      title: Text(
                        doc.get('username', defaultValue: 'Unknown User'),
                      ),
                    );
                  },
                );
              },
            )
          : FutureBuilder(
              future: FirebaseFirestore.instance.collection('posts').get(),
              builder: (context, snapshot) {
                if (snapshot.connectionState == ConnectionState.waiting) {
                  return const Center(child: CircularProgressIndicator());
                }
                if (!snapshot.hasData || snapshot.data!.docs.isEmpty) {
                  return const Center(child: Text("No posts available"));
                }

                return StaggeredGridView.countBuilder(
                  crossAxisCount: 3,
                  itemCount: snapshot.data!.docs.length,
                  itemBuilder: (context, index) => Image.network(
                    snapshot.data!.docs[index].get('postUrl', defaultValue: 'https://via.placeholder.com/300'),
                    fit: BoxFit.cover,
                  ),
                  staggeredTileBuilder: (index) => StaggeredTile.count(
                      (index % 7 == 0) ? 2 : 1, (index % 7 == 0) ? 2 : 1),
                  mainAxisSpacing: 8.0,
                  crossAxisSpacing: 8.0,
                );
              },
            ),
    );
  }
}

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