Flutter读取_JsonQuerySnapshot实例列表返回null问题解决方法

• getData()方法没有定义明确返回值，所有return逻辑都写在then嵌套回调内，函数本身默认返回null，这是你拿到null返回值的核心原因
• 嵌套异步请求没有做等待处理：forEach循环内的子集合查询是异步逻辑，外层函数不会等这些请求执行完就直接结束运行
• 直接把Firestore返回的QuerySnapshot对象存入列表，没有解析快照内的实际业务数据，才会打印出Instance of '_JsonQuerySnapshot'的类型结果
• 没有做异步错误捕获，请求失败时无法被FutureBuilder正常识别

数据请求方法 #

/// 传入父级分类文档ID，返回解析完成的分类数据列表
Future<List<Map<String, dynamic>>> getData(String parentDocId) async {
  final db = FirebaseFirestore.instance;
  List<Map<String, dynamic>> categoryList = [];

  try {
    // 获取父级分类文档
    final DocumentSnapshot parentDoc = await db
        .collection('categories')
        .doc(parentDocId)
        .get();
    // 读取子集合ID列表
    final List<dynamic> subCollectionIds = List.from(
      parentDoc.get("categoryCollection") as List
    );

    // 并行请求所有子集合数据，等待全部请求完成
    final List<QuerySnapshot> subSnapshots = await Future.wait(
      subCollectionIds.map((colId) => db
          .collection('categories')
          .doc(parentDocId)
          .collection(colId.toString())
          .get()
      )
    );

    // 遍历所有快照，解析出实际业务数据
    for (final snapshot in subSnapshots) {
      final docs = snapshot.docs.map((doc) {
        final data = doc.data() as Map<String, dynamic>;
        // 可选：把文档ID存入数据，方便后续更新/删除操作
        data['docId'] = doc.id;
        return data;
      }).toList();
      categoryList.addAll(docs);
    }

    return categoryList;
  } catch (e) {
    rethrow;
  }
}

FutureBuilder 组件代码 #

注意：不要在FutureBuilder的future属性内直接调用请求方法，否则页面每次重建都会重复触发请求。建议在initState中提前初始化请求实例。

class _CategoryPageState extends State<CategoryPage> {
  // 提前初始化请求Future
  late final Future<List<Map<String, dynamic>>> _categoryFuture;

  @override
  void initState() {
    super.initState();
    // 替换为你实际使用的父文档ID变量value
    _categoryFuture = getData(value);
  }

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<List<Map<String, dynamic>>>(
      future: _categoryFuture,
      builder: (context, snapshot) {
        // 错误状态
        if (snapshot.hasError) {
          return const Text("数据加载失败");
        }
        // 加载完成状态
        if (snapshot.connectionState == ConnectionState.done) {
          final categoryData = snapshot.data ?? [];
          print('解析完成的分类数据：$categoryData');
          // 这里替换为你的列表渲染逻辑
          return const Text("数据加载完成");
        }
        // 加载中状态
        return const Center(child: CircularProgressIndicator());
      },
    );
  }
}

• 所有异步逻辑统一用async/await写法，不要在多层嵌套的then回调里写返回值，这类返回值不会被外层函数接收
• 多个无依赖的并行异步请求用Future.wait统一等待执行完成，不要在forEach循环内单独写then处理，这种写法无法准确捕获所有请求的完成时机
• Firestore返回的QuerySnapshot、DocumentSnapshot是查询快照对象，必须调用.data()方法才能拿到实际存储的Map格式业务数据，直接存储快照对象就会出现_JsonQuerySnapshot的类型问题
• 给FutureBuilder指定明确的泛型类型，避免隐式类型转换导致的异常

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