Flutter中ListView.builder使用snapshot.data.length报错问题[已解决]

报错原因 #

• 你使用的FutureBuilder/StreamBuilder未指定泛型，snapshot.data被默认推断为Object?类型，无法直接调用List的length属性
• 未做异步加载状态判断和非空校验，空安全模式下不允许直接对可空类型调用属性
• 如果是对接Cloud Firestore接口，未显式获取文档列表就直接调用属性也会触发该类报错

修复步骤 #

1. 给异步Builder指定明确泛型 #

如果是直接获取文档列表，泛型指定为List<DocumentSnapshot>；如果是获取查询快照，泛型指定为QuerySnapshot，示例为查询快照的常用写法：

StreamBuilder<QuerySnapshot>(
  stream: FirebaseFirestore.instance.collection("你的集合名").snapshots(),
  builder: (context, snapshot) {
    // 后续逻辑写在这里
  }
)

2. 提前做状态和非空判断 #

在渲染ListView之前，先处理加载中、无数据的异常场景，确认数据加载完成且非空后再调用列表属性：

builder: (context, snapshot) {
  // 加载状态处理
  if (snapshot.connectionState == ConnectionState.waiting) {
    return const Center(child: CircularProgressIndicator());
  }
  // 无数据/加载失败处理
  if (!snapshot.hasData || snapshot.data == null) {
    return const Center(child: Text("暂无相关数据"));
  }
  // 非空断言后拿到文档列表
  final docList = snapshot.data!.docs;
  return ListView.builder(
    itemCount: docList.length,
    itemBuilder: (context, index) {
      return ListTile(
        // 新版本Cloud Firestore推荐用get方法取字段，避免类型转换报错
        title: Text(docList[index].get("Identificacao")),
      );
    }
  );
}

补充说明 #

如果你的业务逻辑需要先把快照数据转为自定义的实体类，建议在拿到docList之后统一做序列化处理，避免在itemBuilder里重复做类型转换，也能减少运行时报错概率。

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