Flutter ListView.builder报错：_childElements.containsKey(index)断言失败

错误信息 #

package:flutter/src/widgets/sliver.dart':
Failed assertion: line 1430 pos 14: '_childElements.containsKey(index)': is not true.

问题分析 #

这个断言失败核心原因是ListView.builder的itemCount与实际数据源长度不匹配，常见触发场景：

• 数据源（pickUp）异步更新时，itemCount先更新为新长度，但builder仍在尝试访问旧数据源的无效索引；
• 使用!强制解包可空的pickUp，若数据源为null或中途被置空，会引发索引越界或断言错误；
• 数据源列表在builder执行过程中被直接修改，导致索引失效。

解决方案 #

1. 增加空安全判断，避免强制解包 #

不要直接用!访问可空数据源，先做状态校验，为空时返回占位UI：

SizedBox(
  height: MediaQuery.of(context).size.height / 1.6,
  child: ListView.builder(
    physics: const BouncingScrollPhysics(),
    itemBuilder: (context, index) {
      final pickUpList = HomeCubit.get(context).pickUp;
      // 空判断+索引合法性校验
      if (pickUpList == null || index >= pickUpList.length) {
        return const SizedBox.shrink(); // 或返回加载占位组件
      }
      return Padding(
        padding: const EdgeInsets.symmetric(vertical: 8.0),
        child: PendingContainer(pickUpEntity: pickUpList[index]),
      );
    },
    itemCount: HomeCubit.get(context).pickUp?.length ?? 0,
  ),
)

2. 用状态管理监听确保数据同步 #

通过BlocBuilder监听Cubit状态变化，确保builder拿到的是最新数据源，避免直接在builder中获取Cubit实例：

SizedBox(
  height: MediaQuery.of(context).size.height / 1.6,
  child: BlocBuilder<HomeCubit, HomeState>(
    builder: (context, state) {
      final pickUpList = state.pickUp;
      return ListView.builder(
        physics: const BouncingScrollPhysics(),
        itemBuilder: (context, index) => Padding(
          padding: const EdgeInsets.symmetric(vertical: 8.0),
          child: PendingContainer(pickUpEntity: pickUpList![index]),
        ),
        itemCount: pickUpList?.length ?? 0,
      );
    },
  ),
)

3. 确保数据源不可变，更新时生成新列表 #

修改Cubit中更新数据源的逻辑，避免直接修改原列表，而是生成新列表实例触发状态更新：

// Cubit中更新数据的正确方式
void updatePickUpList(PickUpEntity newItem) {
  final currentList = state.pickUp ?? [];
  emit(HomeState(pickUp: [...currentList, newItem])); // 生成新列表
}

4. 校验数据源更新时机 #

确保在数据源完全加载完成后再更新itemCount，避免异步加载过程中出现长度不匹配的情况。比如在Cubit中先完成数据请求，再emit状态，不要提前更新pickUp。

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