如何在Flutter Cupertino TextField下方显示错误标签

需求说明 #

• 目标交互：用户点击登录按钮触发校验后，若对应CupertinoTextField的输入内容为空，需在文本框下方展示错误提示文本。
• 当前适配难点：CupertinoTextField未内置类似MaterialTextField的errorText参数，无法直接通过组件配置在输入框下方渲染错误标签，需要通过自定义布局实现。
• 现有实现的问题：当前代码中将widget.errorText赋值给输入框的placeholder属性存在逻辑缺陷——占位符仅会在输入框无内容且未聚焦时展示，且位于输入框内部，无法匹配“在文本框下方展示独立错误提示”的交互要求。

原实现代码 #

CupertinoTextField(
  key: widget.key,
  keyboardType: widget.textInputType,
  placeholder: widget.errorText ?? widget.hint,
  style: widget.style,
  onChanged: widget.onChanged,
  enabled: widget.enabled,
  controller: widget.textEditingController,
  focusNode: _focusNode,
  obscureText: widget.obscureText,
  enableSuggestions: widget.enableSuggestions,
  autocorrect: widget.autocorrect,
  clearButtonMode: OverlayVisibilityMode.editing,
  padding: widget.iosPaddings != null
      ? widget.iosPaddings!
      : const EdgeInsets.all(4),
);

可落地实现逻辑 #

• 布局结构调整：使用垂直方向的Column组件包裹原有CupertinoTextField，将错误提示文本作为Column的第二个子元素，放置在输入框下方。
• 状态管理：在组件的State中维护两个核心状态值
  • 布尔值控制错误提示的展示/隐藏
  • 字符串存储当前要展示的错误提示文案
• 交互逻辑绑定：
  • 点击登录按钮触发校验时，若检测到输入框内容为空，更新状态值为“显示错误”，设置对应提示文案
  • 监听输入框的onChanged回调，当用户重新输入有效内容时，自动清除错误状态，隐藏提示文本
• 样式适配：错误提示文本选用警示色（如iOS默认的systemRed），字号略小于输入框正文，和输入框之间保留固定垂直间距，可配合短时长透明度动画优化展示体验。

修改后的参考代码 #

// State内维护的状态变量
String? _errorMsg;
bool _showError = false;

Column(
  crossAxisAlignment: CrossAxisAlignment.stretch,
  children: [
    CupertinoTextField(
      key: widget.key,
      keyboardType: widget.textInputType,
      // 恢复原有占位符逻辑，不再将错误文案塞入placeholder
      placeholder: widget.hint,
      style: widget.style,
      onChanged: (value) {
        // 用户修改输入内容时自动清除错误提示
        if (_showError) {
          setState(() {
            _showError = false;
            _errorMsg = null;
          });
        }
        widget.onChanged?.call(value);
      },
      enabled: widget.enabled,
      controller: widget.textEditingController,
      focusNode: _focusNode,
      obscureText: widget.obscureText,
      enableSuggestions: widget.enableSuggestions,
      autocorrect: widget.autocorrect,
      clearButtonMode: OverlayVisibilityMode.editing,
      padding: widget.iosPaddings != null
          ? widget.iosPaddings!
          : const EdgeInsets.all(4),
    ),
    // 输入框下方的错误提示区域
    if (_showError && _errorMsg != null)
      Padding(
        padding: const EdgeInsets.only(top: 6, left: 4),
        child: Text(
          _errorMsg!,
          style: TextStyle(
            color: CupertinoColors.systemRed,
            fontSize: 12,
          ),
        ),
      ),
  ],
)

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