Flutter键盘开合触发重建，如何避免FutureBuilder重拉数据、TextField内容被重置

问题现象 #

• 个人资料编辑页通过FutureBuilder拉取历史用户Profile数据回填到TextField
• 移动端唤起/收起键盘触发页面尺寸变化时，build方法反复执行，导致FutureBuilder被反复重建、重复发起数据拉取
• 已尝试的临时修复均存在缺陷：
  • 类内定义临时Future变量、仅为null时初始化的方案，仍会出现输入内容被重置的问题
  • 静态计数控制仅首次build赋值的方案，存在静态变量生命周期与页面生命周期不匹配的隐患，缓存数据容易残留
• 接入状态管理后问题复现，排查为状态配置方式不当导致
• 核心目标：首次加载回填历史数据后，编辑过程中无论键盘如何开合，已编辑的输入内容不会被重置，最终可正常提交修改后的资料

根因定位 #

• 将Future对象定义在build方法内部时，每次build都会生成全新的Future实例，FutureBuilder会将其识别为新的异步任务，重新执行全流程拉取、赋值逻辑
• 直接在build流程中给TextField的controller.text赋值，会在每次build时覆盖用户已经输入的编辑内容
• 静态变量缓存方案脱离页面生命周期，容易出现旧数据残留、页面销毁后资源未释放的问题

可直接落地的实现步骤 #

1. 将异步拉取逻辑移出build流程，持有唯一的Future实例
   • 把Future对象定义为State类的成员变量，在initState生命周期中完成初始化，全程保证整个页面生命周期内Future实例唯一，不会因为build重新生成
     示例代码：

   // 类成员变量声明
   late Future<UserProfile> _profileFuture;
   
   @override
   void initState() {
     super.initState();
     // 仅在页面初始化时执行一次拉取，生成固定的Future实例
     _profileFuture = userProfileRepository.fetchCurrentProfile();
   }
   

2. 使用TextEditingController作为输入状态的唯一持有方
   • 为每个需要回填的TextField创建独立的TextEditingController，同样定义为State类成员变量，不要在build流程中临时创建
   • 数据拉取完成后仅执行一次controller赋值操作，后续build流程不再重复触发赋值动作，避免覆盖用户编辑内容
     示例代码：

   // 类成员变量声明
   final _nameInputController = TextEditingController();
   final _bioInputController = TextEditingController();
   
   // 仅在数据首次加载完成后执行一次绑定
   void _bindProfileToControllers(UserProfile profile) {
     _nameInputController.text = profile.nickname;
     _bioInputController.text = profile.bio;
   }
   

3. 调整FutureBuilder的职责边界
   • 让FutureBuilder仅承担加载态、错误态的渲染职责，不在builder回调中直接修改controller内容
   • 为了避免赋值时机的问题，在数据快照返回有效内容后，通过帧回调执行一次controller绑定，且加空判断避免重复赋值
     示例代码：

   @override
   Widget build(BuildContext context) {
     return FutureBuilder<UserProfile>(
       future: _profileFuture,
       builder: (context, snapshot) {
         // 根据快照状态渲染对应页面骨架，不做状态修改
         if (snapshot.connectionState != ConnectionState.done) {
           return const Scaffold(
             body: Center(child: CircularProgressIndicator()),
           );
         }
         if (snapshot.hasError) {
           return const Scaffold(
             body: Center(child: Text('加载失败，请稍后重试')),
           );
         }
         // 帧回调中执行一次性绑定，避免在build流程中直接修改状态
         WidgetsBinding.instance.addPostFrameCallback((_) {
           // 加判断防止重复赋值覆盖用户输入
           if (_nameInputController.text.isEmpty) {
             _bindProfileToControllers(snapshot.data!);
           }
         });
         // 表单内容直接绑定已初始化的controller，和加载状态解耦
         return _buildProfileEditForm();
       },
     );
   }
   

4. 修正状态管理的配置方式（已接入状态管理的场景）
   • 数据拉取逻辑放到状态类的初始化方法中执行，不要在build流程中触发状态拉取动作
   • 状态类持有对应的TextEditingController，数据加载完成后一次性给controller赋值，用户的输入变化直接由controller内部维护，不需要通过状态通知触发全页面build
   • 提交更新时，直接从controller读取当前输入值提交即可，不依赖全量状态同步
5. 资源释放
   • 在State的dispose方法中手动释放所有TextEditingController，避免内存泄漏

最终效果校验 #

• 首次进入页面时正常展示加载态，数据加载完成后自动回填历史内容
• 唤起/收起键盘时，build方法虽然会重新执行，但因为Future实例是唯一的，不会重复发起网络请求
• 编辑过程中所有输入框的内容由controller独立维护，不会被build流程意外重置
• 提交按钮可正常读取当前输入的修改内容，完成资料更新流程

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