Flutter表单管理插件formx的使用

formx 是一个强大的Flutter表单管理插件，它提供了许多便捷的方法来管理表单状态、验证和提交。本文将详细介绍如何使用 formx 插件，并提供完整的示例代码。

1. 安装插件

首先，在 pubspec.yaml 文件中添加 formx 依赖：

dependencies:
  flutter:
    sdk: flutter
  formx: ^latest_version

然后运行 flutter pub get 来安装插件。

2. 基本用法

2.1 访问表单状态

BuildContext.formx([String? key]) 方法可以自动获取当前上下文中的 FormState，也可以通过指定键来访问多个表单中的某个特定表单的状态。

final addressState = context.formx();
// 如果有多个表单：
final addressState = context.formx('address'); 

if (addressState.validate()) {
  final map = addressState.toMap();
  addressState.save(); // 处理map数据
} else {
  throw FormxException(addressState.errorTexts);
}

你也可以为特定字段获取状态：

final emailState = context.field('email');

2.2 提交快捷方式

context.submit('address') 和 context.trySubmit('address') 方法可以一次性完成 .validate()、.save() 和 .toMap() 操作。如果表单无效，则会抛出错误文本。

// 与上面的代码功能相同，但更简洁
final map = context.submit('address');
final mapOrNull = context.trySubmit('address');

建议结合 flutter_async 库来处理错误。

3. 表单状态扩展方法

FormState 的扩展方法包括：

• .toMap({FormxOptions? options})：返回一个包含所有表单值的结构化 Map。
• .rawValues：返回未修改的 FormFieldState.value。
• .initialValues：返回未修改的 FormField.initialValue。
• .isInitial：检查是否有任何字段被初始化。
• .hasInteractedByUser：检查用户是否已与任何字段交互。
• .hasError：检查是否有任何字段出现错误。
• .isValid：检查所有字段是否有效。
• .invalids：返回所有无效字段的键列表。
• .errorTexts：返回所有字段的错误文本。
• .fill(Map<String, dynamic> map)：根据键值对设置每个关联字段。

4. 表单状态扩展类型

FormxState 是一个内联类，重新声明了部分 FormState 方法：

• .validate([List<String>? keys])
• .save([List<String>? keys])
• .reset([List<String>? keys])

这些方法不仅适用于顶层表单，还适用于嵌套表单。

5. 字段状态扩展方法

你可以通过以下方法设置字段的错误文本：

.setErrorText(String? errorText)

需要使用 Validator 类来实现。

6. 全局配置

你可以使用 Formx.setup 来设置全局选项：

Formx.setup(
  defaultTitle: 'Default Title',
  datePicker: (context) => showDatePicker(...),
  filePicker: (context) => FilePicker.platform.pickFiles(),
  filesPicker: (context) => FilePicker.platform.pickFiles(allowMultiple: true),
  fileUploader: (file) async { /* upload logic */ },
  fileDeleter: (file) async { /* delete logic */ },
);

7. 自定义验证器

Validator 类提供了一种可读且声明式的方式来定义验证规则：

TextFormField(
  validator: Validator<String>()
    ..required()
    ..email(),
);

// 或者更简洁的方式：
TextFormField(
  validator: Validator().required().email(),
);

你可以自定义错误文本：

Validator.defaultRequiredText = 'This field is required';
Validator.defaultInvalidText = 'This field is invalid';

Validator.translator = (key, errorText) => '$errorText.$key';

8. 示例代码

以下是一个完整的示例，展示了如何使用 formx 插件构建复杂的表单结构：

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:formx/formx.dart';

void main() {
  runApp(
    const MaterialApp(
      locale: Locale('pt', 'BR'),
      supportedLocales: [Locale('pt', 'BR')],
      localizationsDelegates: GlobalMaterialLocalizations.delegates,
      home: Material(
        child: FormxExample(),
      ),
    ),
  );
}

class FormxExample extends StatelessWidget {
  const FormxExample({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    Validator.translator = (key, errorText) => '$errorText.$key';

    return Scaffold(
      floatingActionButton: const MyWidget(),
      floatingActionButtonLocation: FloatingActionButtonLocation.endTop,
      body: Form(
        key: const Key('user'),
        onChanged: () {
          final state = context.formx();
          print(state.toMap());
        },
        child: Center(
          child: SingleChildScrollView(
            child: Form(
              key: const Key('sub'),
              onChanged: context.debugForm,
              child: Column(
                mainAxisSize: MainAxisSize.min,
                children: [
                  TextFormField(
                    key: const Key('name'),
                    initialValue: 'John Doe',
                    validator: Validator().required().minLength(2),
                  ),
                  TextFormField(
                    key: const Key('phone'),
                    initialValue: '91982224111',
                    inputFormatters: Formatter().phone.br(),
                    validator: Validator().minWords(2),
                  ),
                  TextFormField(
                    key: const Key('email'),
                    initialValue: 'some@email.com',
                    validator: Validator().required().email(),
                  ),
                  Form(
                    key: const Key('address'),
                    onChanged: context.debugForm,
                    child: Column(
                      mainAxisSize: MainAxisSize.min,
                      children: [
                        const Text('Address:'),
                        TextFormField(
                          key: const Key('street'),
                          initialValue: 'Sesame Street',
                        ),
                        CheckboxFormField(
                          key: const Key('terms'),
                          title: const Text('I agree to the terms'),
                          validator: Validator().required(),
                        ),
                      ],
                    ),
                  ),
                  ElevatedButton(
                    onPressed: () {
                      context.submit();
                    },
                    child: const Text('Submit'),
                  ),
                ],
              ),
            ),
          ),
        ),
      ),
    );
  }
}

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () {
        print(context.formx().toMap());
      },
      child: const Text('Print Form'),
    );
  }
}