Flutter中如何将TextFormField的校验错误信息展示在屏幕顶部

TextFormField默认的errorText是绑定在输入框下方的装饰元素，要把错误提示移到屏幕顶部，需要关闭默认的错误提示展示，自行管理全局错误状态，再在顶部渲染错误条即可，具体实现步骤如下：

• 第一步：关闭TextFormField默认错误提示
  在TextFormField的decoration属性中设置errorStyle: TextStyle(height: 0)，这样即使校验不通过，默认的错误文本也不会占用空间显示。
• 第二步：定义全局错误状态存储变量
  在State类中定义可空字符串变量，用于存储当前表单的错误信息：

  String? _formError;
  

• 第三步：在页面顶部新增错误提示区域
  页面布局优先使用Column，最顶部添加错误提示容器，用Visibility控制显隐：

  Visibility(
    visible: _formError != null,
    child: Container(
      width: double.infinity,
      padding: EdgeInsets.all(12),
      color: Colors.redAccent,
      child: Text(
        _formError ?? '',
        style: TextStyle(color: Colors.white, fontSize: 14),
      ),
    ),
  )
  

• 第四步：改写校验逻辑
  原本validator函数返回错误字符串会触发默认提示，现在修改为：校验不通过时，通过setState把错误信息赋值给_formError，validator返回null即可，提交表单前也要清空旧的错误状态。

完整实现代码示例：

import 'package:flutter/material.dart';

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

  @override
  State<TopErrorFormPage> createState() => _TopErrorFormPageState();
}

class _TopErrorFormPageState extends State<TopErrorFormPage> {
  final _formKey = GlobalKey<FormState>();
  String? _formError;
  final TextEditingController _emailController = TextEditingController();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('顶部错误提示表单')),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          children: [
            // 顶部错误提示
            Visibility(
              visible: _formError != null,
              child: Container(
                width: double.infinity,
                padding: const EdgeInsets.all(12),
                margin: const EdgeInsets.only(bottom: 16),
                decoration: BoxDecoration(
                  color: Colors.redAccent,
                  borderRadius: BorderRadius.circular(4),
                ),
                child: Text(
                  _formError ?? '',
                  style: const TextStyle(color: Colors.white, fontSize: 14),
                ),
              ),
            ),
            Form(
              key: _formKey,
              child: Column(
                children: [
                  TextFormField(
                    controller: _emailController,
                    keyboardType: TextInputType.emailAddress,
                    decoration: const InputDecoration(
                      labelText: '邮箱',
                      border: OutlineInputBorder(),
                      // 关闭默认错误提示的高度，避免输入框下方留白
                      errorStyle: TextStyle(height: 0),
                    ),
                    // 输入时清空旧错误提示
                    onChanged: (value) {
                      if (_formError != null) {
                        setState(() => _formError = null);
                      }
                    },
                    validator: (value) {
                      if (value == null || value.isEmpty) {
                        setState(() => _formError = '请输入邮箱地址');
                        return null;
                      }
                      if (!RegExp(r'^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$').hasMatch(value)) {
                        setState(() => _formError = '请输入合法的邮箱格式');
                        return null;
                      }
                      return null;
                    },
                  ),
                  const SizedBox(height: 20),
                  ElevatedButton(
                    onPressed: () {
                      // 提交前清空旧错误
                      setState(() => _formError = null);
                      // 触发校验
                      if (_formKey.currentState!.validate()) {
                        // 校验通过后的业务逻辑
                        ScaffoldMessenger.of(context).showSnackBar(
                          const SnackBar(content: Text('提交成功'))
                        );
                      }
                    },
                    child: const Text('提交表单'),
                  )
                ],
              ),
            )
          ],
        ),
      ),
    );
  }

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

如果需要错误提示自动消失，可以在赋值_formError的时候新增Future.delayed定时逻辑，几秒后自动清空状态即可；如果有多个输入框需要区分错误来源，也可以给_formError增加类型标识，展示对应输入框的错误信息。

内容的提问来源于stack exchange，提问作者Mohammad Al-Kashif