Flutter表单构建插件flutter_form_craft的使用

Flutter表单构建插件flutter_form_craft的使用

简介

Flutter FormCraft插件简化了在Flutter应用中管理表单的过程，提供了方便的工具集来构建和与表单进行交互。

特性

• 表单管理：轻松管理Flutter应用中的FormCraftTextField小部件。
• 验证：使用可定制的验证规则和错误消息验证表单字段。
• 字段交互：程序化地访问、修改和提交表单字段值。
• 自定义：根据应用程序的需求自定义表单字段的行为、外观和验证规则。

为什么使用FormCraft？

FormCraft简化了Flutter中的表单开发，提供了创建、验证和与表单交互的直观API。无论你是在构建简单的登录表单还是复杂的多步骤向导，FormCraft都可以简化表单管理，减少样板代码并加速开发。

开始使用

要在你的Flutter项目中开始使用FormCraft，只需将包添加到你的pubspec.yaml文件中：

dependencies:
  form_craft: ^0.0.1

使用方法

1. FormCraft

FormCraft类是一个强大的工具，旨在简化Flutter应用中表单字段的管理和交互。它的主要目标是简化在Flutter应用中构建和验证表单的过程。

创建FormCraft

final formCraft = FormCraft();

/// 您可以这样构建文本字段。
///
/// 第一个参数是文本字段的键。这是验证表单所必需的。通过使用此键，您可以获取文本字段的值并验证它。还可以找到文本字段的焦点节点。
/// 第二个参数是文本字段的构造函数。您可以使用它来构建您的文本字段。
/// 构造函数只有一个参数。它是文本字段的全局键。您应该将它提供给FormCraftTextField。
_formCraft.buildTextField(
  'new_field',
  (globalKey) => CustomFormTextField(
  globalKey: globalKey,
  ...
  ),
),

/// 您可以通过这种方式获取焦点节点。
final focusNode = _formCraft.getFocusNode('login');
focusNode.requestFocus();

/// FormCraft允许您重新分配文本字段的初始值。或者，您可以随时更改输入文本值。
_formCraft.reassignInputValue('login', 'Initial value for login');

/// 您可以通过这种方式清除表单。
_formCraft.refreshForm();

/// 您可以为表单设置验证类型。默认情况下，它是FormCraftValidationType.onSubmit。
_formCraft.setValidationType(FormCraftValidationType.onSubmit);

验证方式

FormCraft提供两种验证方式：FormCraftValidationType.onSubmit 和 FormCraftValidationType.always。默认是FormCraftValidationType.onSubmit。

1. FormCraftValidationType.onSubmit - 当调用方法时验证表单：

/// 如果表单有效，则返回true。
final isValid = _formCraft.validate()

1. FormCraftValidationType.always - 当开始输入值时验证表单。每个字段将单独验证。

您可以调用方法更改验证类型：

_formCraft.setValidationType(FormCraftValidationType.always);

重要提示：必须在构建小部件后设置验证类型以应用更改。否则，验证类型将不被应用。例如，您可以在initState中执行此操作：

 [@override](/user/override)
  void initState() {
    _formCraft = FormCraft();
    WidgetsBinding.instance.addPostFrameCallback((_) {
      _formCraft.setValidationType(FormCraftValidationType.always);
    });
    super.initState();
  }

2. TextField

1. 在使用该包时，必须使用FormCraftTextField：

FormCraftTextField(...)

1. FormCraft 提供了一个.buildTextField方法，您需要提供FormCraftTextField或自定义文本字段。（不用担心，您可以基于FormCraftTextField创建自己的文本字段）

_formCraft.buildTextField(
  'login',
  (globalKey) => FormCraftTextField(
  /// 全局键是表单验证所必需的。如果您想使用表单验证，应像这样提供全局键。
  globalKey: globalKey,

  /// 与TextFormField相同的方法。
  onChanged: (value) {},

  /// 文本字段的初始值。
  initialValue: 'Initial value for login',

  /// 您可以在这里指定自定义（例如从服务器获取的错误消息等）错误消息。
  customErrorMessage: 'Custom error message for login',
              
  validators: [
    /// 您可以像这样使用内置验证器。
    FormCraftValidator.required(),
  ],
  /// 如果您想为文本字段创建自定义装饰，可以使用decorationBuilder。
  /// 不要忘记提供`errorMessage`以显示错误消息。
  decorationBuilder: (errorMessage) => InputDecoration(
    labelText: 'Login',
    errorText: errorMessage,
  ),

  /// 剩下的部分您可以像在TextFormField中一样处理。
    ),
  ),

1. 当然，您可以创建自定义文本字段：

class CustomFormTextField extends StatelessWidget {
  final Function(String value) onChanged;
  final List<FormCraftFieldValidator>? validators;
  final String? initialValue;
  final Key globalKey;
  const CustomFormTextField({
    required this.onChanged,
    required this.globalKey,
    this.validators,
    this.initialValue,
    super.key,
  });

  [@override](/user/override)
  Widget build(BuildContext context) {
    return FormCraftTextField(
      globalKey: globalKey,
      onChanged: onChanged,
      initialValue: initialValue,
      validators: validators,
      decorationBuilder: (errorMessage) => InputDecoration(
        errorBorder:
            UnderlineInputBorder(borderSide: BorderSide(color: Colors.red)),
        focusedErrorBorder:
            UnderlineInputBorder(borderSide: BorderSide(color: Colors.red)),
        errorText: errorMessage,
      ),
    );
  }
}

3. 验证

FormCraft 提供了一些预定义的验证器：

• FormCraftValidator.required() - 必填文本字段。
• FormCraftValidator.email() - 检查电子邮件是否非空且符合有效的电子邮件格式

FormCraftTextField(
              ...,
              validators: [
                FormCraftValidator.required(),
              ],
            ),
          ),

如果您想更改错误消息，只需传递消息作为参数：

FormCraftTextField(
              ...,
              validators: [
                 FormCraftValidator.email('Please enter a valid email address'),
              ],
            ),
          ),

您还可以创建自己的自定义验证器。FormCraft 提供了两种方法：

1. 使用FormCraftValidator.custom

// 创建您的自定义验证器
FormCraftValidator.custom(
    message: 'Password to short',
    predicate: (input) => input!.length > 6,
  );

FormCraftTextField(
  ...,
  validators: [
  FormCraftValidator.custom(
  message: 'Password to short',
  predicate: (input) => input!.length > 6,
      );
    ],
  ),
),

1. 您可以创建自己的验证器：

class CustomValidator implements FormCraftValidator {
  final String message;

  const CustomValidator({
    required this.message,
  });

  [@override](/user/override)
  String? validate(String input) {
    /// 输入必须大于6个字符。
    /// 如果验证失败则返回错误消息，否则返回`null`。
    return input.length > 6 ? null : message;
  }
}

FormCraftTextField(
  ...,
  validators: [CustomValidator()],
  ),
),

4. 完整示例

class LoginScreen extends StatefulWidget {
  const LoginScreen({super.key});

  [@override](/user/override)
  State<LoginScreen> createState() => _LoginScreenState();
}

class _LoginScreenState extends State<LoginScreen> {
  late final FormCraft _formCraft;
  
  [@override](/user/override)
  void initState() {
    _formCraft = FormCraft();
    /// 您可以像这样更改验证类型。
    WidgetsBinding.instance.addPostFrameCallback((_) {
      _formCraft.setValidationType(FormCraftValidationType.onSubmit);
    });
    super.initState();
  }

  [@override](/user/override)
  void dispose() {
    super.dispose();
    // 不要忘记释放数据。
    _formCraft.dispose();
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          _formCraft.buildTextField(
            'login',
            (globalKey) => FormCraftTextField(
              globalKey: globalKey,
              onChanged: (value) {},
              initialValue: 'Initial value for login',
              customErrorMessage: 'Custom error message for login',
              validators: [
                FormCraftValidator.required(),
              ],
              decorationBuilder: (errorMessage) => InputDecoration(
                labelText: 'Login',
                errorText: errorMessage,
              ),
            ),
          ),
          _formCraft.buildTextField(
            'email',
            (globalKey) => FormCraftTextField(
              globalKey: globalKey,
              onChanged: (value) {},
              validators: [
                FormCraftValidator.email('Please enter the correct email format'),
              ],
            ),
          ),
          ElevatedButton(
            child: Text('Login'),
            onPressed: () {
              final isValid = _formCraft.validate();
              if (isValid) {
                final result = _formCraft.submitForm();
                final loginResult = result['login'];
              }
            },
          )
        ],
      ),
    );
  }
}