Flutter2.5 StreamBuilder推送事件时TextField键盘自动切换问题

安全阿岳

2026-8-30

问题描述

Flutter 2.5版本下存在如下异常：在StreamBuilder中推送TextEditingController事件时，TextField的键盘会从数字输入模式自动切换为字母输入模式。移除事件推送逻辑后异常消失，相同代码在Flutter 2.2.0及更早版本可正常运行，需要保留原有组件刷新逻辑的前提下修复该问题。

原业务实现代码：

void main() {
  runApp(MyApp());
}

final _controller = StreamDataController<TextEditingController>();

var texttype="";
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body:  StreamBuilder<TextEditingController>(
        stream: _controller.stream,
        builder: (context,snapShot){
          return HomeScreen();
        }),
      ),
    );
  }
}


class HomeScreen extends StatefulWidget {
  static final StringBuffer dummyText = StringBuffer();

  @override
  State<HomeScreen> createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
   TextEditingController controllerText= TextEditingController(text: HomeScreen.dummyText.toString());

   @override
   void dispose() {
     super.dispose();
     controllerText.dispose();
   }

  @override
  Widget build(BuildContext context) {
          return TextField(
            controller: controllerText,
            decoration: InputDecoration(
                labelText: "Enter Text here"
            ),

            onChanged: (String text){
              if((text.length - HomeScreen.dummyText.length).abs() == 3){
                controllerText=TextEditingController(text:text);
                HomeScreen.dummyText.write(text);
                _controller.pushEvent(controllerText);
              }
            },
          );
  }
}

class StreamDataController<T> {
  final _controller = StreamController<T>();

  Stream<T> get stream => _controller.stream;

  void pushEvent(T event){
    _controller.sink.add(event);
  }

  void dispose(){
    _controller.close();
  }
}

问题根因

Flutter 2.5版本调整了TextField与键盘的联动校验逻辑：当组件重建时如果检测到绑定的TextEditingController是全新实例，会判定输入组件配置发生变更，自动重新拉起默认的字母键盘，不会保留用户当前选择的数字输入模式。
原有代码在输入回调中反复创建新的TextEditingController实例，再通过Stream触发重建，刚好命中了该逻辑，导致键盘模式反复重置。Flutter 2.2及更早版本没有新增该实例校验逻辑，因此不会出现该问题。

可行修复方案

复用TextEditingController实例，禁止在输入回调或build方法中重复创建controller
将controller的初始化逻辑移到initState生命周期中，全组件生命周期复用同一个实例。需要更新输入内容时，不要新建controller替换，直接修改现有实例的value属性即可：

class _HomeScreenState extends State<HomeScreen> {
  late TextEditingController controllerText;

  @override
  void initState() {
    super.initState();
    controllerText = TextEditingController(text: HomeScreen.dummyText.toString());
  }

  @override
  void dispose() {
    controllerText.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return TextField(
      controller: controllerText,
      keyboardType: TextInputType.number, // 显式声明数字键盘类型，不要依赖默认推断
      decoration: InputDecoration(
          labelText: "Enter Text here"
      ),
      onChanged: (String text){
        if((text.length - HomeScreen.dummyText.length).abs() == 3){
          // 直接更新现有controller的内容和光标位置，不新建实例
          controllerText.value = TextEditingValue(
            text: text,
            selection: TextSelection.collapsed(offset: text.length)
          );
          HomeScreen.dummyText.write(text);
          // 推送事件改为传递文本内容/刷新信号，不要传递新的controller实例
          _controller.pushEvent(text);
        }
      },
    );
  }
}

给TextField绑定稳定标识Key
为TextField设置固定的ValueKey，保证Stream触发组件树重建时，Flutter可以正确识别输入组件的身份，不会误判为全新组件重置状态：
```
TextField(
  key: const ValueKey('custom_input_field'),
  // 其余属性不变
)
```
调整Stream的传参类型
不要将TextEditingController作为Stream的传递参数，TextEditingController本身自带监听能力，不需要通过Stream推送新实例触发刷新。Stream仅用来传递业务需要的刷新信号、最新文本值即可，从根源避免controller实例被意外替换。

注意：如果在build方法中创建TextEditingController，除了键盘模式异常外，还可能出现光标错位、输入内容丢失、内存泄漏等问题，controller的创建和释放必须严格和StatefulWidget的生命周期绑定。

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