输入框及表单

Material widget库中提供了丰富的输入框及表单Widget。下面我们分别介绍一下。

TextField

TextField用于文本输入，它提供了很多属性，我们先简单介绍一下主要属性的作用，然后通过几个示例来演示一下关键属性的用法。

  1. const TextField({
  2.   ...
  3.   TextEditingController controller, 
  4.   FocusNode focusNode,
  5.   InputDecoration decoration = const InputDecoration(),
  6.   TextInputType keyboardType,
  7.   TextInputAction textInputAction,
  8.   TextStyle style,
  9.   TextAlign textAlign = TextAlign.start,
  10.   bool autofocus = false,
  11.   bool obscureText = false,
  12.   int maxLines = 1,
  13.   int maxLength,
  14.   bool maxLengthEnforced = true,
  15.   ValueChanged<String> onChanged,
  16.   VoidCallback onEditingComplete,
  17.   ValueChanged<String> onSubmitted,
  18.   List<TextInputFormatter> inputFormatters,
  19.   bool enabled,
  20.   this.cursorWidth = 2.0,
  21.   this.cursorRadius,
  22.   this.cursorColor,
  23.   ...
  24. })

  • controller：编辑框的控制器，通过它可以设置/获取编辑框的内容、选择编辑内容、监听编辑文本改变事件。大多数情况下我们都需要显式提供一个controller来与文本框交互。如果没有提供controller，则TextField内部会自动创建一个。

  • focusNode：用于控制TextField是否占有当前键盘的输入焦点。它是我们和键盘交互的一个handle。

  • InputDecoration：用于控制TextField的外观显示，如提示文本、背景颜色、边框等。

  • keyboardType：用于设置该输入框默认的键盘输入类型，取值如下：

    | TextInputType枚举值 | 含义 |
    | —————————- | —————————————————————————- |
    | text | 文本输入键盘 |
    | multiline | 多行文本，需和maxLines配合使用(设为null或大于1) |
    | number | 数字；会弹出数字键盘 |
    | phone | 优化后的电话号码输入键盘；会弹出数字键盘并显示”* #” |
    | datetime | 优化后的日期输入键盘；Android上会显示“: -” |
    | emailAddress | 优化后的电子邮件地址；会显示“@ .” |
    | url | 优化后的url输入键盘； 会显示“/ .” |

  • textInputAction：键盘动作按钮图标(即回车键位图标)，它是一个枚举值，有多个可选值，全部的取值列表读者可以查看API文档，下面是当值为TextInputAction.search时，原生Android系统下键盘样式：

    image-20180903181235471

  • style：正在编辑的文本样式。
  • textAlign: 输入框内编辑文本在水平方向的对齐方式。
  • autofocus: 是否自动获取焦点。
  • obscureText：是否隐藏正在编辑的文本，如用于输入密码的场景等，文本内容会用“•”替换。
  • maxLines：输入框的最大行数，默认为1；如果为null，则无行数限制。
  • maxLength和maxLengthEnforced ：maxLength代表输入框文本的最大长度，设置后输入框右下角会显示输入的文本计数。maxLengthEnforced决定当输入文本长度超过maxLength时是否阻止输入，为true时会阻止输入，我false时不会阻止输入但输入框会变红。
  • onChange：输入框内容改变时的回调函数；注：内容改变事件也可以通过controller来监听。
  • onEditingComplete和onSubmitted：这两个回调都是在输入框输入完成时触发，比如按了键盘的完成键（对号图标）或搜索键（?图标）。不同的是两个回调签名不同，onSubmitted回调是ValueChanged<String>类型，它接收当前输入内容做为参数，而onEditingComplete不接收参数。
  • inputFormatters：用于指定输入格式；当用户输入内容改变时，会根据指定的格式来校验。
  • enable：如果为false，则输入框会被禁用，禁用状态不接收输入和事件，同时显示禁用态样式（在其decoration中定义）。
  • cursorWidth、cursorRadius和cursorColor：这三个属性是用于自定义输入框光标宽度、圆角和颜色的。

示例：登录输入框

布局
  1. Column(
  2.         children: <Widget>[
  3.           TextField(
  4.             autofocus: true,
  5.             decoration: InputDecoration(
  6.                 labelText: "用户名",
  7.                 hintText: "用户名或邮箱",
  8.                 prefixIcon: Icon(Icons.person)
  9.             ),
  10.           ),
  11.           TextField(
  12.             decoration: InputDecoration(
  13.                 labelText: "密码",
  14.                 hintText: "您的登录密码",
  15.                 prefixIcon: Icon(Icons.lock)
  16.             ),
  17.             obscureText: true,
  18.           ),
  19.         ],
  20. );

image-20180904111331835

获取输入内容

获取输入内容有两种方式：

  1. 定义两个变量，用于保存用户名和密码，然后在onChange触发时，各自保存一下输入内容。
  2. 通过controller直接获取。

第一种方式比较简单，不在举例，我们来重点看一下第二种方式，我们以用户名输入框举例：

定义一个controller：

  1. //定义一个controller
  2. TextEditingController _unameController=new TextEditingController();

然后设置输入框controller：

  1. TextField(
  2.     autofocus: true,
  3.     controller: _unameController, //设置controller
  4.     ...
  5. )

通过controller获取输入框内容

  1. print(_unameController.text)
监听文本变化

监听文本变化也有两种方式：

  1. 设置onChange回调，如：

    1. TextField(
    2.     autofocus: true,
    3.     onChanged: (v) {
    4.       print("onChange: $v");
    5.     }
    6. )

  2. 通过controller监听，如：

    1. @override
    2. void initState() {
    3.   //监听输入改变  
    4.   _unameController.addListener((){
    5.     print(_unameController.text);
    6.   });
    7. }

两种方式相比，onChanged是专门用于监听文本变化，而controller的功能却多一些，除了能监听文本变化外，它还可以设置默认值、选择文本，下面我们看一个例子：

创建一个controller:

  1. TextEditingController _selectionController = new TextEditingController();

设置默认值，并从第三个字符开始选中后面的字符

  1. _selectionController.text="hello world!";
  2. _selectionController.selection=TextSelection(
  3.     baseOffset: 2,
  4.     extentOffset: _selectionController.text.length
  5. );

设置controller:

  1. TextField(
  2.   controller: _selectionController,
  3. )

运行效果如下：

image-20180904155039251

控制焦点

焦点可以通过FocusNode和FocusScopeNode来控制，默认情况下，焦点由FocusScope来管理，它代表焦点控制范围，可以在这个范围内可以通过FocusScopeNode在输入框之间移动焦点、设置默认焦点等。我们可以通过FocusScope.of(context) 来获取widget树中默认的FocusScopeNode。下面看一个示例，在此示例中创建两个TextField，第一个自动获取焦点，然后创建两个按钮：

  • 点击第一个按钮可以将焦点从第一个TextField挪到第二个TextField。
  • 点击第二个按钮可以关闭键盘。

界面如下：

image-20180904184812329

代码如下：

  1. class FocusTestRoute extends StatefulWidget {
  2.   @override
  3.   _FocusTestRouteState createState() => new _FocusTestRouteState();
  4. }
  6. class _FocusTestRouteState extends State<FocusTestRoute> {
  7.   FocusNode focusNode1 = new FocusNode();
  8.   FocusNode focusNode2 = new FocusNode();
  9.   FocusScopeNode focusScopeNode;
  11.   @override
  12.   Widget build(BuildContext context) {
  13.     return Padding(
  14.       padding: EdgeInsets.all(16.0),
  15.       child: Column(
  16.         children: <Widget>[
  17.           TextField(
  18.             autofocus: true, 
  19.             focusNode: focusNode1,//关联focusNode1
  20.             decoration: InputDecoration(
  21.                 labelText: "input1"
  22.             ),
  23.           ),
  24.           TextField(
  25.             focusNode: focusNode2,//关联focusNode2
  26.             decoration: InputDecoration(
  27.                 labelText: "input2"
  28.             ),
  29.           ),
  30.           Builder(builder: (ctx) {
  31.             return Column(
  32.               children: <Widget>[
  33.                 RaisedButton(
  34.                   child: Text("移动焦点"),
  35.                   onPressed: () {
  36.                     //将焦点从第一个TextField移到第二个TextField
  37.                     // 这是一种写法 FocusScope.of(context).requestFocus(focusNode2);
  38.                     // 这是第二种写法
  39.                     if(null == focusScopeNode){
  40.                       focusScopeNode = FocusScope.of(context);
  41.                     }
  42.                     focusScopeNode.requestFocus(focusNode2);
  43.                   },
  44.                 ),
  45.                 RaisedButton(
  46.                   child: Text("隐藏键盘"),
  47.                   onPressed: () {
  48.                     // 当所有编辑框都失去焦点时键盘就会收起  
  49.                     focusNode1.unfocus();
  50.                     focusNode2.unfocus();
  51.                   },
  52.                 ),
  53.               ],
  54.             );
  55.           },
  56.           ),
  57.         ],
  58.       ),
  59.     );
  60.   }
  62. }

FocusNode和FocusScopeNode还有一些其它的方法，详情可以查看API文档。

监听焦点状态改变事件

FocusNode继承自ChangeNotifier，通过FocusNode可以监听焦点的改变事件，如：

  1. ...
  2. // 创建 focusNode   
  3. FocusNode focusNode = new FocusNode();
  4. ...
  5. // focusNode绑定输入框   
  6. TextField(focusNode: focusNode);
  7. ...
  8. // 监听焦点变化    
  9. focusNode.addListener((){
  10.    print(focusNode.hasFocus);
  11. });

获得焦点时focusNode.hasFocus值为true，失去焦点时为false。

自定义样式

虽然我们可以通过decoration属性来定义输入框样式，但是有一些样式如下划线默认颜色及宽度都是不能直接自定义的，下面的代码没有效果：

  1. TextField(
  2.   ...
  3.   decoration: InputDecoration(
  4.   border: UnderlineInputBorder(
  5.   //下面代码没有效果
  6.   borderSide: BorderSide(
  7.           color: Colors.red,
  8.          width: 5.0
  9.     )),
  10.   prefixIcon: Icon(Icons.person)
  11.   ),
  12. ),

之所以如此，是由于TextField在绘制下划线时使用的颜色是主题色里面的hintColor，但提示文本颜色也是用的hintColor， 如果我们直接修改hintColor，那么下划线和提示文本的颜色都会变。值得高兴的是decoration中可以设置hintStyle，它可以覆盖hintColor，并且主题中可以通过inputDecorationTheme来设置输入框默认的decoration。所以我们可以通过主题来自定义，代码如下：

  1. Theme(
  2.   data: Theme.of(context).copyWith(
  3.       hintColor: Colors.grey[200], //定义下划线颜色
  4.       inputDecorationTheme: InputDecorationTheme(
  5.           labelStyle: TextStyle(color: Colors.grey),//定义label字体样式
  6.           hintStyle: TextStyle(color: Colors.grey, fontSize: 14.0)//定义提示文本样式
  7.       )
  8.   ),
  9.   child: Column(
  10.     children: <Widget>[
  11.       TextField(
  12.         controller: _pwdController,
  13.         decoration: InputDecoration(
  14.             labelText: "密码",
  15.             hintText: "您的登录密码",
  16.             prefixIcon: Icon(Icons.lock)
  17.         ),
  18.         obscureText: true,
  19.       ),
  20.       TextField(
  21.         decoration: InputDecoration(
  22.             prefixIcon: Icon(Icons.search),
  23.             labelText: "密码",
  24.             hintText: "输入关键字搜索",
  25.             hintStyle: TextStyle(color: Colors.grey, fontSize: 13.0)
  26.         ),
  27.       )
  28.     ],
  29.   )
  30. )

运行效果如下：

image-20180904121222620

我们成功的自定义了下划线颜色和提问文字样式，细心的读者可能已经发现，通过这种方式自定义后，输入框在获取焦点时，labelText不会高亮显示了，正如上图中的”用户名”本应该显示蓝色，但现在却显示为灰色，并且我们还是无法定义下划线宽度。另一种灵活的方式是直接隐藏掉TextField本身的下划线，然后通过Container去嵌套定义样式，如:

  1. Container(
  2.   child: TextField(
  3.     keyboardType: TextInputType.emailAddress,
  4.     decoration: InputDecoration(
  5.         labelText: "Email",
  6.         hintText: "电子邮件地址",
  7.         prefixIcon: Icon(Icons.email),
  8.         border: InputBorder.none //隐藏下划线
  9.     )
  10.   ),
  11.   decoration: BoxDecoration(
  12.       // 下滑线浅灰色，宽度1像素
  13.       border: Border(bottom: BorderSide(color: Colors.grey[200], width: 1.0))
  14.   ),
  15. )

运行效果：

image-20180904150511545

通过这种widget组合的方式，也可以定义背景圆角等。一般来说，优先通过decoration来自定义样式，如果decoration实现不了，再用widget组合的方式。

思考题：在这个示例中，下划线颜色是固定的，所以获得焦点后颜色仍然为灰色，如何实现点击后下滑线也变色呢？

表单Form

实际业务中，在正式向服务器提交数据前，都会对各个输入框数据进行合法性校验，但是对每一个TextField都分别进行校验将会是一件很麻烦的事。还有，如果用户想清除一组TextField的内容，除了一个一个清除有没有什么更好的办法呢？为此，Flutter提供了一个Form widget，它可以对输入框进行分组，然后进行一些统一操作，如输入内容校验、输入框重置以及输入内容保存。

Form

Form继承自StatefulWidget对象，它对应的状态类为FormState。我们先看看Form类的定义：

  1. Form({
  2.   @required Widget child,
  3.   bool autovalidate = false,
  4.   WillPopCallback onWillPop,
  5.   VoidCallback onChanged,
  6. })
  • autovalidate：是否自动校验输入内容；当为true时，每一个子FormField内容发生变化时都会自动校验合法性，并直接显示错误信息。否则，需要通过调用FormState.validate()来手动校验。
  • onWillPop：决定Form所在的路由是否可以直接返回（如点击返回按钮），该回调返回一个Future对象，如果Future的最终结果是false，则当前路由不会返回；如果为true，则会返回到上一个路由。此属性通常用于拦截返回按钮。
  • onChanged：Form的任意一个子FormField内容发生变化时会触发此回调。

FormField

Form的子孙元素必须是FormField类型，FormField是一个抽象类，定义几个属性，FormState内部通过它们来完成操作，FormField部分定义如下：

  1. const FormField({
  2.   ...
  3.   FormFieldSetter<T> onSaved, //保存回调
  4.   FormFieldValidator<T>  validator, //验证回调
  5.   T initialValue, //初始值
  6.   bool autovalidate = false, //是否自动校验。
  7. })

为了方便使用，Flutter提供了一个TextFormField widget，它继承自FormField类，也是TextField的一个包装类，所以除了FormField定义的属性之外，它还包括TextField的属性。

FormState

FormState为Form的State类，可以通过Form.of()或GlobalKey获得。我们可以通过它来对Form的子孙FormField进行统一操作。我们看看其常用的三个方法：

  • FormState.validate()：调用此方法后，会调用Form子孙FormField的validate回调，如果有一个校验失败，则返回false，所有校验失败项都会返回用户返回的错误提示。
  • FormState.save()：调用此方法后，会调用Form子孙FormField的save回调，用于保存表单内容
  • FormState.reset()：调用此方法后，会将子孙FormField的内容清空。

示例

我们修改一下上面用户登录的示例，在提交之前校验：

  1. 用户名不能为空，如果为空则提示“用户名不能为空”。
  2. 密码不能小于6位，如果小于6为则提示“密码不能少于6位”。

完整代码：

  1. class FormTestRoute extends StatefulWidget {
  2.   @override
  3.   _FormTestRouteState createState() => new _FormTestRouteState();
  4. }
  6. class _FormTestRouteState extends State<FormTestRoute> {
  7.   TextEditingController _unameController = new TextEditingController();
  8.   TextEditingController _pwdController = new TextEditingController();
  9.   GlobalKey _formKey= new GlobalKey<FormState>();
  11.   @override
  12.   Widget build(BuildContext context) {
  13.     return PageScaffold(
  14.       title: "Form Test",
  15.       body: Padding(
  16.         padding: const EdgeInsets.symmetric(vertical: 16.0, horizontal: 24.0),
  17.         child: Form(
  18.           key: _formKey, //设置globalKey，用于后面获取FormState
  19.           autovalidate: true, //开启自动校验
  20.           child: Column(
  21.             children: <Widget>[
  22.               TextFormField(
  23.                   autofocus: true,
  24.                   controller: _unameController,
  25.                   decoration: InputDecoration(
  26.                       labelText: "用户名",
  27.                       hintText: "用户名或邮箱",
  28.                       icon: Icon(Icons.person)
  29.                   ),
  30.                   // 校验用户名
  31.                   validator: (v) {
  32.                     return v
  33.                         .trim()
  34.                         .length > 0 ? null : "用户名不能为空";
  35.                   }
  37.               ),
  38.               TextFormField(
  39.                   controller: _pwdController,
  40.                   decoration: InputDecoration(
  41.                       labelText: "密码",
  42.                       hintText: "您的登录密码",
  43.                       icon: Icon(Icons.lock)
  44.                   ),
  45.                   obscureText: true,
  46.                   //校验密码
  47.                   validator: (v) {
  48.                     return v
  49.                         .trim()
  50.                         .length > 5 ? null : "密码不能少于6位";
  51.                   }
  52.               ),
  53.               // 登录按钮
  54.               Padding(
  55.                 padding: const EdgeInsets.only(top: 28.0),
  56.                 child: Row(
  57.                   children: <Widget>[
  58.                     Expanded(
  59.                       child: RaisedButton(
  60.                         padding: EdgeInsets.all(15.0),
  61.                         child: Text("登录"),
  62.                         color: Theme
  63.                             .of(context)
  64.                             .primaryColor,
  65.                         textColor: Colors.white,
  66.                         onPressed: () {
  67.                           //在这里不能通过此方式获取FormState，context不对
  68.                           //print(Form.of(context));
  70.                           // 通过_formKey.currentState 获取FormState后，
  71.                           // 调用validate()方法校验用户名密码是否合法，校验
  72.                           // 通过后再提交数据。 
  73.                           if((_formKey.currentState as FormState).validate()){
  74.                             //验证通过提交数据
  75.                           }
  76.                         },
  77.                       ),
  78.                     ),
  79.                   ],
  80.                 ),
  81.               )
  82.             ],
  83.           ),
  84.         ),
  85.       ),
  86.     );
  87.   }
  88. }

运行后：

image-20180904174217682

注意，登录按钮的onPressed方法中不能通过Form.of(context)来获取，原因是，此处的context为FormTestRoute的context，而Form.of(context)是根据所指定context向根去查找，而FormState是在FormTestRoute的子树中，所以不行。正确的做法是通过Builder来构建登录按钮，Builder会将widget节点的context作为回调参数：

  1. Expanded(
  2.  // 通过Builder来获取RaisedButton所在widget树的真正context(Element) 
  3.   child:Builder(builder: (context){
  4.     return RaisedButton(
  5.       ...
  6.       onPressed: () {
  7.         //由于本widget也是Form的子代widget，所以可以通过下面方式获取FormState  
  8.         if(Form.of(context).validate()){
  9.           //验证通过提交数据
  10.         }
  11.       },
  12.     );
  13.   })
  14. )

其实context正是操作Widget所对应的Element的一个接口，由于Widget树对应的Element都是不同的，所以context也都是不同的，有关context的更多内容会在后面高级部分详细讨论。Flutter中有很多“of(context)”这种方法，在使用时读者一定要注意context是否正确。