TextField

处理文本输入的核心组件

TextField是Flutter中用于处理文本输入的核心组件，允许用户通过键盘输入文本。它支持单行或多行输入、文本验证、样式自定义以及交互事件(如onChanged)。逻辑上，TextField内部使用TextEditingController管理文本状态，并可集成焦点控制、表单验证等功能。适用于登录表单、搜索框、聊天输入框等场景。

使用场景

数据输入: 如用户注册时输入用户名或密码。
实时搜索: 在搜索栏中动态过滤内容。
交互反馈: 例如在评论框中输入文本并提交。

示例

基础文本输入

TextField(
  decoration: InputDecoration(
    labelText: '请输入姓名',
    border: OutlineInputBorder(),
  ),
  onChanged: (value) {
    print('当前输入: $value');
  },
)

带验证的密码输入

class PasswordField extends StatefulWidget {
  @override
  _PasswordFieldState createState() => _PasswordFieldState();
}

class _PasswordFieldState extends State<PasswordField> {
  final TextEditingController _controller = TextEditingController();
  String _errorText;

  void _validateInput(String value) {
    setState(() {
      _errorText = value.length < 6 ? '密码至少6位' : null;
    });
  }

  @override
  Widget build(BuildContext context) {
    return TextField(
      controller: _controller,
      obscureText: true, // 隐藏输入文本
      decoration: InputDecoration(
        labelText: '密码',
        errorText: _errorText,
        border: OutlineInputBorder(),
      ),
      onChanged: _validateInput,
    );
  }
}

主题适配的多行输入

TextField(
  maxLines: 3, // 多行输入
  decoration: InputDecoration(
    hintText: '请输入描述...',
    filled: true,
    fillColor: Colors.grey[100],
    enabledBorder: UnderlineInputBorder(
      borderSide: BorderSide(color: Colors.blue),
    ),
  ),
  style: TextStyle(fontSize: 16, color: Colors.black87),
  onSubmitted: (value) {
    // 提交时处理
    ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text('提交: $value')));
  },
)

注意点

常见问题

性能瓶颈: 避免在onChanged中执行高开销操作(如网络请求)，可使用防抖(debounce)优化。
兼容性警告: 在iOS和Android上，键盘行为可能不同(如“完成”按钮文本)。
内存泄漏: 如果使用TextEditingController，需在StatefulWidget的dispose方法中调用controller.dispose()。

优化技巧

对于表单，优先使用TextFormField集成验证器。
使用FocusNode管理焦点，以提升用户体验(如自动聚焦到下一个字段)。

最佳实践

为无障碍功能设置semanticLabel。
在暗色主题下测试颜色对比度。

构造函数

TextField的构造函数参数如下(列出关键参数):

Key? key: 组件的唯一标识符。
TextEditingController? controller: 控制文本编辑的控制器。
InputDecoration? decoration: 定义输入框的装饰样式。
ValueChanged<String>? onChanged: 文本变化时的回调函数。
bool obscureText: 是否隐藏文本(用于密码输入)。
int? maxLines: 最大行数，默认为1(单行)。
TextInputType? keyboardType: 键盘类型(如数字键盘)。
初始化时，如果不提供controller，TextField会内部创建一个，但建议显式管理以保持状态可控。

属性

属性名	属性类型	说明
`controller`	`TextEditingController?`	控制文本内容，用于读取或修改输入值。
`decoration`	`InputDecoration?`	定义边框、标签、提示文本等样式。
`onChanged`	`ValueChanged<String>?`	文本变化时触发的回调。
`obscureText`	`bool`	设置为true时隐藏输入文本（如密码字段），默认为false。
`maxLines`	`int?`	最大行数；null表示无限制，1为单行。
`keyboardType`	`TextInputType?`	指定键盘类型（如TextInputType.emailAddress用于邮箱输入）。
`style`	`TextStyle?`	输入文本的样式（如字体、颜色）。
`focusNode`	`FocusNode?`	管理焦点状态，用于程序化控制焦点。

关键属性解释

controller: 核心属性，通过它可监听文本变化或设置初始值，避免直接在onChanged中更新状态导致循环。
decoration: 高度可定制，但复杂装饰可能影响渲染性能；优先使用预定义样式如OutlineInputBorder。
maxLines: 设置多行时，注意与maxLength结合使用以避免溢出。

Text inputs

Cupertino Design