Flutter：TextFormField按下上下箭头键触发异常且无法切换焦点

问题原因 #

当焦点在单行TextFormField上按下上下箭头时，Flutter默认会尝试执行光标垂直移动操作，但单行输入框没有多行文本内容，导致内部断言isValid失败，抛出异常。我们需要重写上下箭头的按键逻辑，让它执行焦点切换而非光标移动。

解决方案 #

方案一：用Shortcuts全局覆盖快捷键行为 #

通过Shortcuts包装表单，将上下箭头映射到焦点切换动作，替换默认的光标移动行为：

class LoginPage extends StatefulWidget {
  const LoginPage({super.key});

  @override
  State<LoginPage> createState() => _LoginPageState();
}

class _LoginPageState extends State<LoginPage> {
  final FocusNode _usernameFocus = FocusNode();
  final FocusNode _passwordFocus = FocusNode();

  @override
  void dispose() {
    _usernameFocus.dispose();
    _passwordFocus.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Shortcuts(
        shortcuts: {
          // 向下箭头 → 切换到下一个焦点
          const SingleActivator(LogicalKeyboardKey.arrowDown): const NextFocusAction(),
          // 向上箭头 → 切换到上一个焦点
          const SingleActivator(LogicalKeyboardKey.arrowUp): const PreviousFocusAction(),
        },
        child: FocusTraversalGroup(
          child: Padding(
            padding: const EdgeInsets.all(16.0),
            child: Column(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                TextFormField(
                  key: const Key('loginForm_usernameInput_textField'),
                  focusNode: _usernameFocus,
                  textInputAction: TextInputAction.next,
                  decoration: const InputDecoration(labelText: '用户名'),
                  onFieldSubmitted: (_) => _passwordFocus.requestFocus(),
                ),
                const SizedBox(height: 16),
                TextFormField(
                  focusNode: _passwordFocus,
                  textInputAction: TextInputAction.done,
                  decoration: const InputDecoration(labelText: '密码'),
                  obscureText: true,
                  onFieldSubmitted: (_) => _passwordFocus.unfocus(),
                ),
              ],
            ),
          ),
        ),
      ),
    );
  }
}

方案二：在TextFormField的onKey中单独处理 #

如果不想全局修改，可在每个输入框的onKey回调中拦截上下箭头事件，手动切换焦点：

TextFormField(
  key: const Key('loginForm_usernameInput_textField'),
  focusNode: _usernameFocus,
  textInputAction: TextInputAction.next,
  decoration: const InputDecoration(labelText: '用户名'),
  onKey: (node, event) {
    if (event.logicalKey == LogicalKeyboardKey.arrowDown) {
      _passwordFocus.requestFocus();
      return KeyEventResult.handled; // 标记事件已处理，阻止默认行为
    }
    return KeyEventResult.ignored;
  },
),
TextFormField(
  focusNode: _passwordFocus,
  textInputAction: TextInputAction.done,
  decoration: const InputDecoration(labelText: '密码'),
  obscureText: true,
  onKey: (node, event) {
    if (event.logicalKey == LogicalKeyboardKey.arrowUp) {
      _usernameFocus.requestFocus();
      return KeyEventResult.handled;
    }
    return KeyEventResult.ignored;
  },
),

说明 #

• 两种方案都需要使用FocusNode手动控制焦点切换，记得在组件销毁时调用dispose()释放资源。
• Shortcuts方案适合全局统一行为，onKey方案更灵活，可针对单个输入框定制逻辑。

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