Flutter 含stateful widgets的动态ListView失效：setState后显示不匹配

问题本质 #

这是Flutter Widget树元素复用机制触发的典型错位问题，和你的列表业务逻辑没有关系。
你在itemBuilder里打印日志拿到的是正确的索引对应数据，但框架更新列表时，默认是靠位置匹配规则来复用同位置下的StatefulWidget状态的：

• 初始列表渲染3个条目时，索引0、1、2位置分别创建了绑定FoodItem-1、FoodItem-2、FoodItem-3数据的3个独立State实例
• 当你把列表更新为只剩[FoodItem-2]时，框架检测到索引0位置需要渲染一个FoodItem组件，不会主动创建新的State，而是直接复用原来索引0位置已经存在的、绑着FoodItem-1数据的State实例
• 虽然你给组件传了FoodItem-2的参数，但旧State里留存的动画状态、本地缓存值根本没有跟着参数同步更新，最终就出现了「日志打印正确、界面显示错位」的现象。

之前用无状态的StatelessWidget没遇到过这个问题，本质是因为StatelessWidget不持有可留存的本地状态，只要参数变化就会全量重新构建内容，自然不会出现旧状态残留的错位。

可落地的解决方案 #

方案1：给列表项绑定稳定的唯一Key（官方推荐的标准解法） #

这也是框架专门为Stateful列表项设计的错位问题解决方案，只需要在返回的FoodItem组件上，传入和条目数据强绑定的唯一标识作为Key即可：

return FoodItem(
  key: ValueKey(searchableFoodList[index].id),
  id: searchableFoodList[index].id,
  // 其余原有入参保持不变
);

加上这个Key之后，框架的State复用规则会从「位置匹配」切换为「Key值匹配」，如果当前位置的组件Key和原有复用的State的Key对不上，就会自动销毁旧State、新建匹配当前数据的State实例，从根源上解决错位问题。

方案2：短列表场景替换为常规ListView渲染 #

如果你的列表条目量不大（通常百条以内的短列表），完全可以把按需构建的ListView.builder换成普通的ListView，直接映射现有列表数据作为子元素：

Expanded(
  child: ListView(
    padding: EdgeInsets.all(10.0),
    children: searchableFoodList.map((foodItem) => FoodItem(
      id: foodItem.id,
      baseUnit: foodItem.baseUnit,
      baseUnitS: foodItem.baseUnitS,
      baseVal: foodItem.baseVal,
      baseValCal: foodItem.baseValCal,
      mediumVal: foodItem.mediumVal,
      mediumValCal: foodItem.mediumValCal,
      name: foodItem.name,
      note: foodItem.note,
    )).toList(),
  ),
)

这种方式没有builder模式的位置匹配复用逻辑，短列表下的性能损耗几乎可以忽略，也能规避错位问题。

方案3：在FoodItem内部做状态同步兜底 #

如果因为业务限制暂时不能给组件加Key，可以在FoodItem的State里重写didUpdateWidget生命周期，主动检测新旧参数的差异，手动重置组件内部的本地状态、动画值：

@override
void didUpdateWidget(covariant FoodItem oldWidget) {
  super.didUpdateWidget(oldWidget);
  // 当检测到条目id变化时，重置组件内所有动画、本地缓存状态
  if (oldWidget.id != widget.id) {
    // 在这里补充重置动画控制器、清空临时状态的逻辑
  }
}

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