Flutter表单管理插件form_controller的使用

form_controller 是一个用于组合多个 TextEditingController 并管理表单状态的控制器。它可以帮助开发者更方便地处理表单输入、验证和重置。

开始使用

1. 添加依赖

在项目的 pubspec.yaml 文件中添加 form_controller：

dependencies:
  form_controller: [latest version]

然后运行以下命令安装依赖：

$ flutter pub get

2. 导入库

在需要使用的 Dart 文件中导入 form_controller：

import 'package:form_controller/form_controller.dart';

示例代码

以下是一个完整的示例，展示如何使用 form_controller 来管理表单。

import 'dart:developer';
import 'package:flutter/material.dart';
import 'package:form_controller/form_controller.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter FormController Demo',
      home: Example(),
    );
  }
}

class Example extends StatefulWidget {
  @override
  _ExampleState createState() => _ExampleState();
}

class _ExampleState extends State<Example> {
  // 声明并初始化 FormController
  late FormController _formController;

  @override
  void initState() {
    super.initState();
    _formController = FormController(controllers: ['val1', 'val2', 'val3']);
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Form(
        // 使用 FormController 提供的 key
        key: _formController.key,
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          crossAxisAlignment: CrossAxisAlignment.center,
          children: [
            // 字段1
            const Text("field1"),
            TextFormField(
              controller: _formController.controller("val1"),
            ),
            // 字段2
            const Text("field2"),
            TextFormField(
              // 可以通过 key 实现特定字段的验证
              key: _formController.fieldStateKey("val2"),
              controller: _formController.controller("val2"),
            ),
            // 字段3
            const Text("field3"),
            TextFormField(
              // 设置初始文本
              controller: _formController.controller("val3", initialText: "Initial Text!"),
            ),
            // 字段4（带验证）
            const Text("field4"),
            TextFormField(
              controller: _formController.controller("val4"),
              // 自定义验证规则
              validator: FormControllerValidators.validate([
                FormControllerValidators.isRequired(),
                FormControllerValidators.minLength(10),
              ]),
            ),
            // 获取数据按钮
            MaterialButton(
              onPressed: () {
                // 获取字段值
                debugPrint("Con1: " + _formController.value("val1"));
                debugPrint("Con2: " + _formController.value("val2"));
                debugPrint("Con3: " + _formController.value("val3"));

                // 调用表单状态方法
                _formController.reset(); // 重置表单
                _formController.validate(); // 验证表单
                _formController.save(); // 保存表单数据
              },
              child: const Text("Get data!"),
            ),
            // 设置字段值
            MaterialButton(
              onPressed: () {
                _formController.set('val2', "This is the new text!");
              },
              child: const Text("Set V2 data!"),
            ),
            // 单独验证某个字段
            MaterialButton(
              onPressed: () {
                _formController.validateOnly("val2");
              },
              child: const Text("Validate V2 data!"),
            ),
            // 字段值流
            StreamBuilder<String>(
              stream: _formController.valueStream("val1"),
              builder: (context, snapshot) {
                return Text("Stream of V1: ${snapshot.data}");
              },
            ),
            // 控制字段的隐藏状态
            Row(
              children: [
                TextFormField(
                  controller: _formController.controller("val5", isObscure: true),
                ),
                MaterialButton(
                  onPressed: () {
                    _formController.toggleObscurity('val5');
                  },
                  child: Icon(Icons.remove_red_eye),
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }
}

// 在使用完成后释放资源
@override
void dispose() async {
  await _formController.dispose();
  super.dispose();
}

功能详解

1. 初始化控制器
   使用 FormController 初始化表单，并传入需要管理的控制器列表。

   late FormController _formController;
   _formController = FormController(controllers: ['val1', 'val2', 'val3']);
   

2. 获取表单控件
   使用 controller 方法获取指定 ID 的 TextEditingController。

   TextFormField(
     controller: _formController.controller("val1"),
   )
   

3. 设置初始值
   可以通过 initialText 参数为控制器设置初始值。

   TextFormField(
     controller: _formController.controller("val3", initialText: "Initial Text!"),
   )
   

4. 验证字段
   支持自定义验证规则，例如必填项和最小长度。

   validator: FormControllerValidators.validate([
     FormControllerValidators.isRequired(),
     FormControllerValidators.minLength(10),
   ])
   

5. 控制字段状态
   可以通过 toggleObscurity 方法切换密码框的隐藏状态。

   MaterialButton(
     onPressed: () {
       _formController.toggleObscurity('val5');
     },
     child: Icon(Icons.remove_red_eye),
   )
   

6. 监听字段变化
   使用 valueStream 监听字段的变化。

   StreamBuilder<String>(
     stream: _formController.valueStream("val1"),
     builder: (context, snapshot) {
       return Text("Stream of V1: ${snapshot.data}");
     },
   )
   

7. 重置表单
   使用 reset 方法清空所有字段。

   _formController.reset();
   

8. 保存表单数据
   使用 save 方法保存表单数据。

   _formController.save();
   

9. 单独验证字段
   使用 validateOnly 方法单独验证某个字段。

   _formController.validateOnly("val2");