Flutter表单验证插件ready_form的使用

ReadyForm 是一个用于简化表单处理的Widget。它可以帮助你进行表单验证，并且在验证失败时滚动到第一个无效项。

功能

• 验证子元素
• 如果验证失败，则滚动到第一个无效项
• 可以添加揭示效果
• ProgressButton 与之平滑配合使用

使用方法

基本用法

return ReadyForm(
  onPostData: () async {
    /// 提交你的数据
    return OnPostDataResult();
  },
  child: ListView(
    children: [
      TextFormField(),
      TextFormField(),
      TextFormField(),
      TextFormField(),
      ProgressButton(child: Text("登录")),
    ],
  ),
);

当你按下进度按钮时，表单将被提交并检查验证规则。

自定义提交方式

如果你需要自行提交表单或不使用 ProgressButton，可以使用 ReadyFormKey。

final ReadyFormKey formKey = ReadyFormKey();

Widget build(BuildContext context) {
  return ReadyForm(
    onPostData: () async {
      /// 提交你的数据
      return OnPostDataResult();
    },
    child: ListView(
      children: [
        TextFormField(),
        TextFormField(),
        TextFormField(),
        TextFormField(),
        ElevatedButton(
          onPressed: () {
            formKey.onSubmit();
          },
          child: Text("登录"),
        ),
      ],
    ),
  );
}

你也可以通过 ReadyForm.of(context) 来访问父表单：

return ReadyForm(
  onPostData: () async {
    /// 提交你的数据
    return OnPostDataResult();
  },
  child: ListView(
    children: [
      TextFormField(),
      TextFormField(),
      TextFormField(),
      TextFormField(),
      Builder(builder: (context) {
        // 当前上下文现在可以访问父表单
        return ElevatedButton(
          onPressed: () {
            ReadyForm.of(context)!.onSubmit();
          },
          child: Text("登录"),
        );
      }),
    ],
  ),
);

全局配置

你可以通过 ReadyFormConfig 配置所有表单。

键盘操作

有一个名为 KeyboardActions 的Widget，它会在键盘打开时在顶部添加三个按钮：“下一个”、“上一个”和“隐藏键盘”。这些图标在iOS上特别有用，因为iOS键盘本身没有隐藏按钮。

默认情况下，ReadyForm 使用此Widget，但你可以在单个表单中禁用它。你也可以单独使用此Widget。

确保此Widget正常工作，你需要传递首选的 FocusTraversalPolicy（建议使用 OrderedTraversalPolicy），并且每个字段都需要用 FocusTraversalOrder 包裹。

FocusTraversalOrder(
  order: NumericFocusOrder(1),
  child: ...,
)

验证模式

每个表单都可以设置验证模式，而不是使用Flutter的 AutoValidateMode 枚举。你可以使用 FormAutoValidateMode，其中包含 onSubmit。

这也可以全局配置。

滚动到无效字段

默认情况下，该包会在 [onSubmit] 时滚动到第一个无效字段。

但是有时你可能想要覆盖这种行为：

EnsureContextVisible(
  after: (context) async {
    /// 这将在默认行为之后调用
  },
  before: (context) async {
    /// 这将在默认行为之前调用
  },
);

EnsureContextVisible.override(
  ensureVisible: (context) async {
    /// 这将覆盖默认行为
  },
);

如果要包裹单个字段，可以这样做：

if (yourCondition) {
  EnsureContextVisible.override(
    ensureVisible: (context) async {
      // 自定义滚动逻辑
    },
  );
}

提交错误

有时你希望在调用 onPostData 后显示自定义错误。

如你所见，onPostData 可以返回 OnPostDataResult，其中可能包含错误映射。从 onPostData 返回的错误不会影响循环，但它们可以通过两种方式向用户展示。

使用 ReadyFormErrorMessages

这个Widget可以显示提交错误信息，你也可以使用自定义构建器来自定义UI。

如果你使用了构建器，你还可以访问无效字段。

return ReadyForm(
  onPostData: () async {
    /// 提交你的数据
    return OnPostDataResult({
      "email": "该电子邮件已存在"
    });
  },
  child: ListView(
    children: [
      ReadyFormErrorMessages(),
      TextFormField(),
      TextFormField(),
      TextFormField(),
      TextFormField(),
      ProgressButton(child: Text("登录")),
    ],
  ),
);

使用 SubmitErrorMessageFor

这个Widget用于显示指定键的错误。

return ReadyForm(
  onPostData: () async {
    /// 提交你的数据
    return OnPostDataResult({
      "email": "该电子邮件已存在"
    });
  },
  child: ListView(
    children: [
      TextFormField(),
      SubmitErrorMessageFor(messageFor: 'email'),
      TextFormField(),
      TextFormField(),
      TextFormField(),
      ProgressButton(child: Text("登录")),
    ],
  ),
);

/// 或者如果你需要显示该字段的其他错误

return ReadyForm(
  onPostData: () async {
    return OnPostDataResult({"email": "该电子邮件已存在"});
  },
  child: ListView(
    children: [
      SubmitErrorMessageFor(
        messageFor: 'email',
        builder: (form, error) {
          return TextFormField(
            decoration: InputDecoration(
              errorText: error,
              hintText: "电子邮件",
            ),
          );
        },
      ),
      TextFormField(),
      TextFormField(),
      TextFormField(),
      ProgressButton(child: Text("登录")),
    ],
  ),
);

示例代码

以下是完整的示例代码：

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

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

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const FormPage(),
    );
  }
}

class FormPage extends StatelessWidget {
  const FormPage({Key? key}) : super(key: key);

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(),
      body: ReadyForm(
        autoValidateMode: FormAutoValidateMode.onSubmit,
        onPostData: () async {
          await Future.delayed(const Duration(milliseconds: 300));
          return OnPostDataResult({"email": "该电子邮件已存在"});
        },
        child: ListView(
          padding: const EdgeInsets.all(20),
          children: [
            SubmitErrorMessageFor(
              messageFor: 'email',
              builder: (form, error) {
                return TextFormField(
                  decoration: InputDecoration(
                    errorText: error,
                    hintText: "电子邮件",
                  ),
                );
              },
            ),
            TextFormField(),
            const SubmitErrorMessageFor(messageFor: 'email'),
            TextFormField(),
            TextFormField(),
            TextFormField(),
            TextFormField(),
            TextFormField(),
            ProgressButton(
              onPressed: () async {
                await Future.delayed(const Duration(seconds: 3));
              },
              child: const Text("登录"),
            )
          ],
        ),
      ),
    );
  }
}