Flutter表单管理插件super_form的使用

Flutter表单管理插件super_form的使用

管理表单状态在Flutter中可能非常繁琐。Super Form 可以帮助你轻松管理表单值、错误以及输入是否被触碰等属性,而无需复杂的逻辑。此外,它还提供了一系列现成的表单组件,但实现自己的组件也非常简单。

你可以访问superform.dev查看示例!

使用

1. 创建SuperForm小部件

在表单顶部创建一个 SuperForm 小部件,就像你使用 Form 一样。你可能希望添加一个 GlobalKey,但这不是必需的。

SuperForm(
  validationMode: ValidationMode.onBlur,
  onSubmit: (values) {
    // 处理表单提交
    print(values.toString());
  },
  child: Column(...),
)

2. 创建字段

TextSuperFormField(
  decoration: const InputDecoration(labelText: "Email"),
  name: "email",
  rules: [RequiredRule("必须填写")],
),

3. 添加提交按钮

OutlinedButton(
  onPressed: () => SuperForm.of(context, listen: false).submit(),
  child: const Text("登录"),
),

注意,你可能需要将 SuperForm 的子组件(如提交按钮)包裹在一个 Builder 中,以便在同一组件中获取 SuperForm 实例。

验证

Super Form 提供了一组验证规则。这些规则相对简单且同步执行。每个规则接受一个错误消息作为参数,当值未通过验证时会自动显示该错误消息。这意味着你可以组合这些规则并显示非常有用的错误信息。

注意规则的顺序很重要。验证从列表的开头开始。

TextSuperFormField(
  decoration: const InputDecoration(labelText: "密码"),
  name: "password",
  rules: [
    RequiredRule("必须填写"),
    MinimumLengthRule(
      6,
      "至少需要6个字符",
    ),
    CustomRule((value) {
      final strength = estimatePasswordStrength(value ?? "");

      if (strength < 0.3) return "密码太弱";
    })
  ],
),

要创建自己的规则,你可以扩展 SuperFormFieldRule,现有规则或使用 CustomRule,后者接受一个函数作为其参数。

动态规则和字段

Super Form 是完全反应式的,因此可以在运行时更改规则和字段。

对于规则,你只需为字段小部件传递不同的规则列表。如果字段已经验证过,它将自动重新验证。

对于字段本身,你可以选择性地构建或不构建它们,它们将相应地注册或取消注册。

验证模式

验证总是在表单提交时运行,之后无效字段将在更改时重新验证。但是,你可以通过向 SuperForm 小部件传递 validationMode 来自定义初始行为。

  • onSubmit(默认)- 验证仅在提交时触发
  • onBlur - 当字段失去焦点时也会触发验证
  • onChange - 字段值更改时触发验证

虚拟字段

有时你需要在表单中有一个字段,但没有实际的控件。Super Form 可以做到这一点!你只需要手动注册该字段。你可以在 SuperForm 小部件的 onInit 回调中轻松完成此操作。

SuperForm(
  onInit: (form) {
    form.register(
      name: "termsAndConditionsAccepted",
      rules: [IsEqualRule(true, '必须接受条款')],
    );
  },
  // ...
)

注册字段后,你可以触发所有标准操作,如设置值、标记为已触碰或触发验证。提交表单也将验证此字段。

程序化交互

Super Form 使得程序化交互变得非常简单,比如设置值。只需从上下文中检索 SuperForm 实例即可。记住,字段必须已注册。

例如,你想使用 showDatePicker 收集表单数据:

showDatePicker(
  context: context,
  initialDate: DateTime.now(),
  firstDate: DateTime.now(),
  lastDate: DateTime.utc(2040),
).then((value) {
  SuperForm.of(context, listen: false).setValue("to", value);
});

错误

通常情况下,你不需要担心显示错误,因为字段会自动处理。但在某些情况下,你可能没有字段的小部件,但仍想显示任何可能的错误。这时 SuperFormErrorText 就能派上用场了。它会显示一个错误消息,并使用主题中的 errorColor

SuperFormErrorText(name: "termsAndConditionsAccepted")

初始值

为字段提供初始值非常简单。只需向 SuperForm 小部件提供字段名称及其初始值的映射。更改此属性不会立即影响表单 - 新的初始值将在字段重置后使用,可以通过 SuperFormState 上的 reset 方法来重置。

SuperForm(
  initialValues: const {"quantity": 1},
  onSubmit: (values) {
    // 处理表单提交
    print(values.toString());
  },
  child: // ...
);

更多关于Flutter表单管理插件super_form的使用的实战教程也可以访问 https://www.itying.com/category-92-b0.html

1 回复

更多关于Flutter表单管理插件super_form的使用的实战系列教程也可以访问 https://www.itying.com/category-92-b0.html


当然,super_form 是一个强大的 Flutter 插件,用于简化表单管理。它允许你以声明式的方式定义表单字段,并且提供了许多便捷的功能来处理表单验证和状态管理。以下是一个简单的示例,展示如何使用 super_form 来管理表单。

首先,确保你已经在 pubspec.yaml 文件中添加了 super_form 依赖:

dependencies:
  flutter:
    sdk: flutter
  super_form: ^最新版本号

然后,运行 flutter pub get 来安装依赖。

接下来,我们创建一个简单的表单,包括用户名和密码字段,并添加一些基本的验证规则。

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

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: MyFormScreen(),
    );
  }
}

class MyFormScreen extends StatefulWidget {
  @override
  _MyFormScreenState createState() => _MyFormScreenState();
}

class _MyFormScreenState extends State<MyFormScreen> {
  final _formKey = GlobalKey<SuperFormState>();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Super Form Example'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: SuperForm(
          key: _formKey,
          children: [
            // Username field
            SuperFormField<String>(
              name: 'username',
              builder: (context, field) {
                return TextField(
                  decoration: InputDecoration(labelText: 'Username'),
                  controller: field.controller,
                );
              },
              validators: [
                Validators.required(context, 'Username is required'),
                Validators.minLength(context, 3, 'Username must be at least 3 characters long'),
              ],
            ),

            // Password field
            SuperFormField<String>(
              name: 'password',
              builder: (context, field) {
                return TextField(
                  decoration: InputDecoration(labelText: 'Password'),
                  obscureText: true,
                  controller: field.controller,
                );
              },
              validators: [
                Validators.required(context, 'Password is required'),
                Validators.minLength(context, 6, 'Password must be at least 6 characters long'),
              ],
            ),

            // Submit button
            ElevatedButton(
              onPressed: () async {
                final form = _formKey.currentState!;
                final result = await form.validate();
                if (result.isValid) {
                  final values = form.values;
                  print('Form Submitted: ${values.toJson()}');
                } else {
                  print('Form has errors: ${result.errors.values.join(', ')}');
                }
              },
              child: Text('Submit'),
            ),
          ],
        ),
      ),
    );
  }
}

在这个示例中,我们做了以下几件事:

  1. 使用 SuperForm 组件来包裹表单字段。
  2. 使用 SuperFormField 来定义每个表单字段,包括用户名和密码。
  3. 为每个字段添加了验证器,例如 Validators.requiredValidators.minLength
  4. 添加了一个提交按钮,当点击按钮时,会触发表单验证。如果表单验证通过,则打印表单值;如果验证失败,则打印错误信息。

这样,通过使用 super_form,你可以很方便地管理复杂的表单,而无需手动处理每个字段的验证和状态。

回到顶部