TextField

预览

在Flutter的 TextField 中，许多参数可以定制输入框的行为、外观和功能。

TextField(
  controller: TextEditingController(),      // 用于管理和获取输入内容
  focusNode: FocusNode(),                   // 管理焦点，控制 TextField 的焦点状态
  decoration: InputDecoration(              // 装饰和样式设置
    border: OutlineInputBorder(),           // 输入框边框样式
    filled: false,                          // 是否填充颜色
    fillColor: Colors.white,                // 填充的颜色
    labelText: 'Enter your text',           // 提示标签，输入时会浮动在上方
    hintText: 'Hint text here',             // 占位文本，在输入前显示的灰色提示
    prefixIcon: Icon(Icons.person),         // 在输入框前添加图标
    suffixIcon: Icon(Icons.clear),          // 在输入框后添加图标，常用于清除按钮
    isCollapsed: true,                      // 折叠，使输入框高度与输入区域相同，默认false
    contentPadding: EdgeInsets.all(2),      // 边框与内容的间距
    isDense: true,
  ),
  keyboardType: TextInputType.text,         // 指定键盘类型，例如 TextInputType.number 打开数字键盘
  textInputAction: TextInputAction.done,    // 输入动作按钮的样式，如完成、搜索、下一步等
  style: TextStyle(fontSize: 16),           // 控制文本输入内容的样式，如字体大小、颜色
  textAlign: TextAlign.start,               // 设置文本对齐方式，例如居左、居中、居右等
  maxLength: 20,                            // 输入字符最大长度
  maxLines: 1,                              // 设置输入框的最大行数，为 null 时输入框可扩展
  obscureText: false,                       // 设置是否隐藏文本，常用于密码输入框
  autofocus: true,                          // 是否自动获取焦点并弹出键盘
  enabled: true,                            // 设置输入框是否可用
  readOnly: false,                          // 设为 true 可实现只读
  onChanged: (text) {                       // 输入内容变化时的回调
    print("Text changed: $text");
  },
  onSubmitted: (text) {                     // 用户提交输入时触发
    print("Submitted text: $text");
  },
  onEditingComplete: () {                   // 编辑完成时触发，不管是否提交
    print("Editing completed");
  },
  cursorColor: Colors.blue,                 // 设置光标颜色
  cursorWidth: 2.0,                         // 设置光标宽度
  cursorHeight: 20.0,                       // 设置光标高度
  cursorRadius: Radius.circular(5),         // 设置光标的圆角
  enableSuggestions: true,                  // 是否开启拼写建议（在某些设备上有效）
  enableInteractiveSelection: true,         // 允许选择和复制文本
  textCapitalization: TextCapitalization.words,  // 自动首字母大写，可选 none, words, sentences, characters
  keyboardAppearance: Brightness.dark,      // 键盘的主题颜色，可以是亮色或暗色
  scrollPadding: EdgeInsets.all(20.0),      // 滚动时的内边距
  scrollPhysics: BouncingScrollPhysics(),   // 设置滚动行为，常用于长文本
)

参数说明

控制器和焦点管理

controller (TextEditingController)

用于管理和获取输入内容，可以设置初始值、清空内容、获取当前文本等。

TextEditingController _controller = TextEditingController();

// 设置初始值
_controller.text = "初始文本";

// 获取当前输入内容
String currentText = _controller.text;

// 清空内容
_controller.clear();

// 监听文本变化
_controller.addListener(() {
  print("当前文本: ${_controller.text}");
});

focusNode (FocusNode)

管理输入框的焦点状态，可以主动获取或失去焦点。

FocusNode _focusNode = FocusNode();

// 主动获取焦点
_focusNode.requestFocus();

// 失去焦点
_focusNode.unfocus();

// 监听焦点变化
_focusNode.addListener(() {
  if (_focusNode.hasFocus) {
    print("获得焦点");
  } else {
    print("失去焦点");
  }
});

外观装饰 (decoration)

边框样式 (border)

// 无边框
decoration: InputDecoration(
  border: InputBorder.none,
)

// 下划线边框
decoration: InputDecoration(
  border: UnderlineInputBorder(
    borderSide: BorderSide(color: Colors.blue, width: 2.0),
  ),
)

// 外边框
decoration: InputDecoration(
  border: OutlineInputBorder(
    borderRadius: BorderRadius.circular(10.0),
    borderSide: BorderSide(color: Colors.grey, width: 1.0),
  ),
)

// 不同状态的边框
decoration: InputDecoration(
  enabledBorder: OutlineInputBorder(
    borderSide: BorderSide(color: Colors.grey),
  ),
  focusedBorder: OutlineInputBorder(
    borderSide: BorderSide(color: Colors.blue, width: 2.0),
  ),
  errorBorder: OutlineInputBorder(
    borderSide: BorderSide(color: Colors.red),
  ),
)

填充和颜色

decoration: InputDecoration(
  filled: true,                    // 启用填充
  fillColor: Colors.grey[100],     // 填充颜色
  hoverColor: Colors.blue[50],     // 鼠标悬停颜色
)

文本和图标

decoration: InputDecoration(
  labelText: '用户名',              // 标签文本，会浮动显示
  hintText: '请输入用户名',          // 占位提示文本
  helperText: '用户名长度为3-20个字符', // 帮助文本
  errorText: '用户名不能为空',       // 错误提示文本
  
  prefixIcon: Icon(Icons.person),   // 前置图标
  suffixIcon: Icon(Icons.clear),    // 后置图标
  prefixText: '+86 ',               // 前置文本
  suffixText: '@example.com',       // 后置文本
  
  counterText: '',                  // 计数器文本（设为空字符串可隐藏）
)

键盘类型 (keyboardType)

// 文本键盘（默认）
keyboardType: TextInputType.text,

// 数字键盘
keyboardType: TextInputType.number,

// 电话号码键盘
keyboardType: TextInputType.phone,

// 邮箱键盘
keyboardType: TextInputType.emailAddress,

// URL键盘
keyboardType: TextInputType.url,

// 多行文本
keyboardType: TextInputType.multiline,

// 带小数点的数字键盘
keyboardType: TextInputType.numberWithOptions(decimal: true),

// 带符号的数字键盘
keyboardType: TextInputType.numberWithOptions(signed: true),

输入动作 (textInputAction)

// 完成
textInputAction: TextInputAction.done,

// 下一步
textInputAction: TextInputAction.next,

// 搜索
textInputAction: TextInputAction.search,

// 发送
textInputAction: TextInputAction.send,

// 前往
textInputAction: TextInputAction.go,

// 加入
textInputAction: TextInputAction.join,

// 换行
textInputAction: TextInputAction.newline,

文本样式和对齐

// 文本样式
style: TextStyle(
  fontSize: 16.0,
  fontWeight: FontWeight.bold,
  color: Colors.black,
  letterSpacing: 1.0,
  height: 1.5,
),

// 文本对齐
textAlign: TextAlign.start,    // 左对齐
textAlign: TextAlign.center,   // 居中对齐
textAlign: TextAlign.end,      // 右对齐
textAlign: TextAlign.justify,  // 两端对齐

// 文本方向
textDirection: TextDirection.ltr,  // 从左到右
textDirection: TextDirection.rtl,  // 从右到左

输入限制

// 最大长度
maxLength: 20,

// 最大行数
maxLines: 1,        // 单行
maxLines: 3,        // 固定3行
maxLines: null,     // 无限制，可扩展

// 最小行数
minLines: 2,

// 是否扩展高度以填充父容器
expands: false,

输入格式化

// 输入格式化器
inputFormatters: [
  FilteringTextInputFormatter.digitsOnly,           // 只允许数字
  FilteringTextInputFormatter.allow(RegExp(r'[a-zA-Z]')), // 只允许字母
  LengthLimitingTextInputFormatter(10),             // 限制长度
  UpperCaseTextFormatter(),                         // 自定义格式化器
],

// 文本首字母大写
textCapitalization: TextCapitalization.none,       // 无
textCapitalization: TextCapitalization.words,      // 单词首字母大写
textCapitalization: TextCapitalization.sentences,  // 句子首字母大写
textCapitalization: TextCapitalization.characters, // 所有字母大写

光标设置

// 光标颜色
cursorColor: Colors.blue,

// 光标宽度
cursorWidth: 2.0,

// 光标高度
cursorHeight: 20.0,

// 光标圆角
cursorRadius: Radius.circular(5.0),

// 显示光标
showCursor: true,

交互行为

// 自动获取焦点
autofocus: true,

// 启用输入框
enabled: true,

// 只读模式
readOnly: false,

// 隐藏文本（密码输入）
obscureText: true,

// 隐藏字符
obscuringCharacter: '*',

// 启用建议
enableSuggestions: true,

// 启用交互式选择
enableInteractiveSelection: true,

// 自动校正
autocorrect: true,

回调函数

// 文本改变时触发
onChanged: (String value) {
  print('输入内容: $value');
},

// 提交时触发（按回车或完成按钮）
onSubmitted: (String value) {
  print('提交内容: $value');
},

// 编辑完成时触发
onEditingComplete: () {
  print('编辑完成');
},

// 点击时触发
onTap: () {
  print('点击了输入框');
},

// 应用私有命令
onAppPrivateCommand: (String action, Map<String, dynamic> data) {
  print('私有命令: $action');
},

滚动相关

// 滚动内边距
scrollPadding: EdgeInsets.all(20.0),

// 滚动物理效果
scrollPhysics: BouncingScrollPhysics(),    // 弹性滚动
scrollPhysics: ClampingScrollPhysics(),    // 夹紧滚动
scrollPhysics: NeverScrollableScrollPhysics(), // 禁止滚动

// 滚动控制器
scrollController: ScrollController(),

其他设置

// 键盘外观
keyboardAppearance: Brightness.light,  // 亮色键盘
keyboardAppearance: Brightness.dark,   // 暗色键盘

// 智能引号和破折号
smartQuotesType: SmartQuotesType.enabled,
smartDashesType: SmartDashesType.enabled,

// 选择控件
selectionControls: MaterialTextSelectionControls(),

// 工具栏选项
toolbarOptions: ToolbarOptions(
  copy: true,
  cut: true,
  paste: true,
  selectAll: true,
),

// 拖拽开始行为
dragStartBehavior: DragStartBehavior.start,

// 鼠标光标
mouseCursor: SystemMouseCursors.text,

// 构建计数器
buildCounter: (context, {required currentLength, required isFocused, maxLength}) {
  return Text('$currentLength/$maxLength');
},

inputDecorationTheme

可以通过 InputDecorationTheme 全局设置 TextField 的主题：

const InputDecorationTheme({
  super.key,
  TextStyle? labelStyle,                        // 标签文本样式
  TextStyle? floatingLabelStyle,                // 浮动标签文本样式（当标签浮动到上方时）
  TextStyle? helperStyle,                       // 帮助文本样式
  int? helperMaxLines,                          // 帮助文本最大行数
  TextStyle? hintStyle,                         // 提示文本样式
  Duration? hintFadeDuration,                    // 提示文本淡入淡出的持续时间
  int? hintMaxLines,                            // 提示文本最大行数
  TextStyle? errorStyle,                        // 错误文本样式
  int? errorMaxLines,                           // 错误文本最大行数
  FloatingLabelBehavior? floatingLabelBehavior, // 浮动标签行为（auto、always、never）
  FloatingLabelAlignment? floatingLabelAlignment, // 浮动标签对齐方式（start、center）
  bool? isDense,                                // 是否使用紧凑布局，减少垂直间距
  EdgeInsetsGeometry? contentPadding,            // 内容内边距（边框与输入文本的间距）
  bool? isCollapsed,                            // 是否折叠，使输入框高度与输入区域相同
  Color? iconColor,                             // 图标颜色
  TextStyle? prefixStyle,                       // 前缀文本样式
  Color? prefixIconColor,                       // 前缀图标颜色
  BoxConstraints? prefixIconConstraints,        // 前缀图标的尺寸约束
  TextStyle? suffixStyle,                        // 后缀文本样式
  Color? suffixIconColor,                       // 后缀图标颜色
  BoxConstraints? suffixIconConstraints,        // 后缀图标的尺寸约束
  TextStyle? counterStyle,                       // 计数器文本样式
  bool? filled,                                 // 是否填充背景颜色
  Color? fillColor,                             // 填充背景颜色
  BorderSide? activeIndicatorBorder,             // 活动指示器边框（用于下划线样式）
  BorderSide? outlineBorder,                    // 轮廓边框（用于外边框样式）
  Color? focusColor,                            // 获得焦点时的颜色
  Color? hoverColor,                            // 鼠标悬停时的颜色
  InputBorder? errorBorder,                     // 错误状态下的边框样式
  InputBorder? focusedBorder,                   // 获得焦点时的边框样式
  InputBorder? focusedErrorBorder,              // 获得焦点且错误时的边框样式
  InputBorder? disabledBorder,                  // 禁用状态下的边框样式
  InputBorder? enabledBorder,                   // 启用状态下的边框样式
  InputBorder? border,                          // 默认边框样式
  bool? alignLabelWithHint,                     // 标签是否与提示文本对齐
  BoxConstraints? constraints,                 // 输入框的尺寸约束
  VisualDensity? visualDensity,                 // 视觉密度（compact、standard、comfortable）
  InputDecorationThemeData? data,               // 主题数据对象
  Widget? child,                                // 子组件
})