Flutter中用户名/密码字段错误时hintText与边框变红异常排查

我需要实现登录表单中用户名和密码字段在错误状态下，hintText与边框均变为红色的效果，但目前仅密码字段能正常显示错误样式，用户名字段的hintText和边框未按预期切换为红色。

通过自定义TextFieldWidget封装输入字段，在_onSubmit方法中先清空错误状态，执行表单验证；验证通过则调用登录接口，若接口返回含"username"的错误信息，会设置_usernameError，但此时用户名字段的红色样式未生效，密码字段在对应错误场景下正常。

问题现象 #

• 仅密码字段在错误时显示红色hintText与边框，用户名字段无对应样式变化。

相关代码 #

自定义TextFieldWidget

class TextFieldWidget {
  static Widget buildTextField({
    required TextEditingController controller,
    required String fieldTitle,
    required String hintText,
    bool isPassword = false,
    required BuildContext context,
    bool obscureText = false,
    void Function()? toggleVisibility,
    String? errorText,
    String? Function(String?)? validator,
  }) {
    final hasError = errorText != null;

    return Padding(
      padding: const EdgeInsets.symmetric(horizontal: 10.5),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(
            fieldTitle,
            style: const TextStyle(
              color: Colors.black,
            ),
          ),
          const SizedBox(height: 8.0),
          TextFormField(
            controller: controller,
            obscureText: obscureText,
            decoration: InputDecoration(
              errorText: hasError ? errorText : null,
              errorStyle: const TextStyle(color: Colors.red),
              hintText: hintText,
              hintStyle: TextStyle(
                color: hasError ? Colors.red : Colors.black.withOpacity(0.8),
              ),
              filled: true,
              fillColor: hasError ? Colors.red.shade50 : Colors.grey.shade300,
              suffixIcon: isPassword
                  ? IconButton(
                      icon: Icon(
                        obscureText
                            ? Icons.visibility
                            : Icons.visibility_off,
                        color: hasError ? Colors.red : Colors.grey,
                      ),
                      onPressed: toggleVisibility,
                    )
                  : null,
              border: OutlineInputBorder(
                borderRadius: BorderRadius.circular(10.0),
                borderSide: BorderSide(
                  color: hasError ? Colors.red : Colors.transparent,
                  width: 1.5,
                ),
              ),
              enabledBorder: OutlineInputBorder(
                borderRadius: BorderRadius.circular(10.0),
                borderSide: BorderSide(
                  color: hasError ? Colors.red : Colors.grey,
                  width: 1.5,
                ),
              ),
              focusedBorder: OutlineInputBorder(
                borderRadius: BorderRadius.circular(10.0),
                borderSide: BorderSide(
                  color: hasError ? Colors.red : Colors.black,
                  width: 1.5,
                ),
              ),
              errorBorder: OutlineInputBorder(
                borderRadius: BorderRadius.circular(10.0),
                borderSide: const BorderSide(
                  color: Colors.red,
                  width: 1.5,
                ),
              ),
              focusedErrorBorder: OutlineInputBorder(
                borderRadius: BorderRadius.circular(10.0),
                borderSide: const BorderSide(
                  color: Colors.red,
                  width: 1.5,
                ),
              ),
            ),
            validator: validator,
            style: TextStyle(
              color: hasError ? Colors.red : Colors.black,
            ),
          ),
        ],
      ),
    );
  }
}

字段使用方式

TextFieldWidget.buildTextField(
  controller: _userNameController,
  fieldTitle: 'Username',
  hintText: 'Enter your username',
  context: context,
  errorText: _usernameError, // Error text if any
  validator: (value) {
    if (value == null || value.trim().isEmpty) {
      return 'Username is required';
    }
    return null;
  },
),

const SizedBox(height: 15.0),

TextFieldWidget.buildTextField(
  controller: _passwordController,
  fieldTitle: 'Password',
  hintText: 'Enter your password',
  isPassword: true,
  context: context,
  obscureText: obscureText,
  toggleVisibility: () {
    ref.read(obscureTextProvider.notifier).state = !obscureText;
  },
  errorText: _passwordError,
),

提交函数

Future<void> _onSubmit() async {
  setState(() {
    _usernameError = null;
    _passwordError = null;
  });

  bool isFormValid = _formKey.currentState!.validate();

  if (isFormValid) {
    final name = _userNameController.text;
    final password = _passwordController.text;

    try {
      await ref.read(authProvider).login(name, password, rememberMe: _rememberMe);
      Navigator.pushReplacement(
        context,
        MaterialPageRoute(builder: (_) => const HomeMainScreen()),
      );
    } catch (e) {
      setState(() {
        _errorMessage = e.toString();
        if (_errorMessage!.contains('username')) {
          _usernameError = _errorMessage;
        } else if (_errorMessage!.contains('password')) {
          _passwordError = _errorMessage;
        }
      });
    }
  }
}

变量定义

String? _errorMessage;
String? _usernameError;
String? _passwordError;
late TextEditingController _userNameController;
late TextEditingController _passwordController;

解决方案 #

问题核心：用户名字段的validator返回null（表单验证通过后），Flutter的TextFormField会优先使用validator的状态，忽略手动传入的errorText。

方案一：调整验证逻辑，优先识别手动错误

1. 修改TextFieldWidget中的validator逻辑，让它优先返回传入的errorText：

validator: (value) {
  if (errorText != null) return errorText;
  return validator?.call(value);
},

2. 在_onSubmit的错误捕获块中，重新触发表单验证：

catch (e) {
  setState(() {
    _errorMessage = e.toString();
    if (_errorMessage!.contains('username')) {
      _usernameError = _errorMessage;
    } else if (_errorMessage!.contains('password')) {
      _passwordError = _errorMessage;
    }
  });
  // 重新触发验证，更新字段状态
  _formKey.currentState!.validate();
}

方案二：移除validator，手动做空值检查

1. 移除用户名字段的validator参数：

TextFieldWidget.buildTextField(
  controller: _userNameController,
  fieldTitle: 'Username',
  hintText: 'Enter your username',
  context: context,
  errorText: _usernameError,
),

2. 在_onSubmit中手动做空值校验：

Future<void> _onSubmit() async {
  setState(() {
    _usernameError = null;
    _passwordError = null;
  });

  // 手动检查空值
  if (_userNameController.text.trim().isEmpty) {
    setState(() => _usernameError = 'Username is required');
    return;
  }
  if (_passwordController.text.trim().isEmpty) {
    setState(() => _passwordError = 'Password is required');
    return;
  }

  final name = _userNameController.text;
  final password = _passwordController.text;

  try {
    await ref.read(authProvider).login(name, password, rememberMe: _rememberMe);
    Navigator.pushReplacement(
      context,
      MaterialPageRoute(builder: (_) => const HomeMainScreen()),
    );
  } catch (e) {
    setState(() {
      _errorMessage = e.toString();
      if (_errorMessage!.contains('username')) {
        _usernameError = _errorMessage;
      } else if (_errorMessage!.contains('password')) {
        _passwordError = _errorMessage;
      }
    });
  }
}

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