Flutter表单管理插件stateful_form的使用

简介

stateful_form 是一个用于简化 Flutter 表单验证和状态管理的插件。它可以帮助开发者轻松地处理表单输入的校验逻辑，并提供友好的错误提示。

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

示例代码

import 'package:flutter/material.dart';
import 'package:stateful_form/stateful_form.dart';

// 定义用户名字段
class UsernameField extends StatefulFormTextField {
  const UsernameField({required super.controller});

  @override
  String? validate() {
    return value.isNotEmpty ? null : '用户名不能为空';
  }
}

// 定义密码字段
class PasswordField extends StatefulFormTextField {
  const PasswordField({required super.controller});

  @override
  String? validate() {
    if (value.isEmpty) {
      return '密码不能为空';
    }
    if (value.length > 20) {
      return '密码太长了';
    }
    if (value.length < 8) {
      return '密码太短了';
    }
    return null;
  }
}

// 主应用页面
class Example extends StatefulWidget {
  const Example({super.key});

  @override
  State<Example> createState() => _ExampleState();
}

class _ExampleState extends State<Example> {
  final _usernameController = TextEditingController();
  final _passwordController = TextEditingController();
  final _form = StatefulForm();

  @override
  void initState() {
    super.initState();
    _form.fields = [
      UsernameField(controller: _usernameController),
      PasswordField(controller: _passwordController),
    ];
  }

  @override
  void dispose() {
    _usernameController.dispose();
    _passwordController.dispose();
    _form.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    int count = 0;
    return Scaffold(
      appBar: AppBar(title: const Text('登录示例')),
      body: SingleChildScrollView(
        padding: const EdgeInsets.all(20),
        child: StatefulFormBuilder(
          form: _form,
          builder: (context, state, child) {
            return Column(
              children: [
                // 用户名输入框
                TextField(
                  controller: _usernameController,
                  decoration: InputDecoration(
                    labelText: '用户名',
                    errorText: state.errorText<UsernameField>(),
                  ),
                ),
                // 密码输入框
                TextField(
                  controller: _passwordController,
                  obscureText: true,
                  decoration: InputDecoration(
                    labelText: '密码',
                    errorText: state.errorText<PasswordField>(),
                  ),
                ),
                // 登录按钮
                Container(
                  padding: const EdgeInsets.only(top: 20),
                  width: 200,
                  child: ElevatedButton(
                    onPressed: () {
                      // 验证表单
                      if (!_form.validate()) {
                        return;
                      }

                      // 模拟密码错误逻辑
                      if (_passwordController.text == '00000000') {
                        _form.setError<PasswordField>('密码错误');
                        return;
                      }

                      // 第一次提交时设置通用错误
                      if (count++ == 0) {
                        _form.setError('服务器异常，请稍后再试');
                        return;
                      }

                      // 成功提示
                      showDialog<void>(
                        context: context,
                        builder: (context) => const AlertDialog(
                          title: Text('登录成功'),
                          actions: [CloseButton()],
                        ),
                      );
                    },
                    child: const Text('登录'),
                  ),
                ),
                // 显示全局错误
                if (state.errorText() != null) ...[
                  const SizedBox(height: 10),
                  Text(
                    state.errorText()!,
                    textAlign: TextAlign.center,
                    style: const TextStyle(color: Colors.red),
                  ),
                ]
              ],
            );
          },
        ),
      ),
    );
  }
}

使用步骤详解

1. 安装插件

在 pubspec.yaml 文件中添加依赖：

dependencies:
  stateful_form: ^0.1.0

然后运行 flutter pub get。

2. 创建自定义表单字段

通过继承 StatefulFormTextField 来创建自定义表单字段，并实现 validate() 方法以定义校验逻辑。

例如：

class UsernameField extends StatefulFormTextField {
  const UsernameField({required super.controller});

  @override
  String? validate() {
    return value.isNotEmpty ? null : '用户名不能为空';
  }
}

3. 初始化表单

在 StatefulWidget 中初始化 StatefulForm 并添加字段：

final _form = StatefulForm();

@override
void initState() {
  super.initState();
  _form.fields = [
    UsernameField(controller: _usernameController),
    PasswordField(controller: _passwordController),
  ];
}

4. 表单验证

调用 _form.validate() 方法进行表单验证：

if (!_form.validate()) {
  return;
}

可以针对特定字段验证：

_form.validate([PasswordField]);

5. 错误渲染

使用 StatefulFormBuilder 渲染表单状态和错误信息：

StatefulFormBuilder(
  form: _form,
  builder: (context, state, child) {
    return Column(
      children: [
        TextField(
          controller: _usernameController,
          decoration: InputDecoration(
            labelText: '用户名',
            errorText: state.errorText<UsernameField>(),
          ),
        ),
        TextField(
          controller: _passwordController,
          obscureText: true,
          decoration: InputDecoration(
            labelText: '密码',
            errorText: state.errorText<PasswordField>(),
          ),
        ),
      ],
    );
  },
)

6. 手动设置错误

可以通过 _form.setError() 方法手动设置错误信息：

_form.setError<PasswordField>('密码错误');
_form.setError('服务器异常，请稍后再试');