Flutter快速表单构建插件flutter_fast_forms的使用

Flutter Fast Forms 是一个用于快速构建 Flutter 表单的 Dart 包。它为 Flutter SDK 添加了一些缺失的功能，简化了表单的创建和管理。以下是关于如何使用 flutter_fast_forms 的详细介绍。

目录

• 概述
• 开始使用
• 控件目录
• 自适应表单控件
• 条件表单控件
• 自定义表单控件

概述

功能特性

• FastFormControl<T>：封装了 Material 和 Cupertino 表单控件，方便快捷地创建表单字段。
• FastForm：提供当前表单字段值的 onChanged 回调。
• FastFormArray：聚合多个同类型控件。
• FastChipsInput：将文本输入转换为芯片（Chip）。
• 条件表单字段：根据其他字段的状态动态启用或禁用字段。
• 验证状态：支持 touched 状态的验证。
• 常用验证器：提供常用的 FormFieldValidator<T> 函数。

开始使用

1. 添加 FastForm 到你的 widget 树中

class MyFormPage extends StatelessWidget {
  MyFormPage({Key? key, required this.title}) : super(key: key);

  final formKey = GlobalKey<FormState>();
  final String title;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(title),
      ),
      body: SafeArea(
        child: SingleChildScrollView(
          child: FastForm(
            formKey: formKey,
            children: [],
          ),
        ),
      ),
    );
  }
}

2. 添加 FastFormControl<T> 子控件到 FastForm

FastForm(
  formKey: formKey,
  children: [
    const FastTextField(
      name: 'field_destination',
      labelText: 'Destination',
      placeholder: 'Where are you going?',
    ),
    FastDateRangePicker(
      name: 'field_check_in_out',
      labelText: 'Check-in - Check-out',
      firstDate: DateTime.now(),
      lastDate: DateTime.now().add(const Duration(days: 365)),
    ),
    const FastCheckbox(
      name: 'field_travel_purpose',
      labelText: 'Travel purpose',
      titleText: 'I am travelling for work',
    ),
  ],
),

3. 使用 FastFormSection 进行视觉分组和一致的内边距

FastForm(
  formKey: formKey,
  children: [
    FastFormSection(
      header: const Text('My Form'),
      padding: EdgeInsets.all(16.0),
      children: [
        const FastTextField(
          name: 'field_destination',
          labelText: 'Destination',
          placeholder: 'Where are you going?',
        ),
        // ...
      ],
    ),
  ]
),

控件目录

自适应表单控件

默认情况下，Flutter Fast Forms 在所有平台上使用 Material 风格的组件。可以通过设置 adaptive 属性为 true 来在 iOS 上自动渲染对应的 Cupertino 组件。

示例：在 iOS 上始终使用 Cupertino 组件

FastForm(
  formKey: formKey,
  adaptive: true,
  children: [
    const FastSwitch(
      name: 'switch',
      titleText: 'Disable text field',
    ),
    FastTextField(
      name: 'text_field',
      labelText: 'Just some sample text field',
    ),    
  ]
),

示例：仅在 iOS 上使用 Cupertino 组件

FastForm(
  formKey: formKey,
  children: [
    const FastSwitch(
      name: 'switch',
      adaptive: true,
      titleText: 'Disable text field when selected',
    ),
  ]
),

条件表单控件

通过条件表单控件，可以根据其他控件的状态动态启用或禁用某些字段。

示例：当开关被选中时禁用文本框

const FastSwitch(
  name: 'switch',
  titleText: 'Disable text field when selected',
),
FastTextField(
  name: 'text_field',
  labelText: 'Just some sample text field',
  conditions: {
    FastCondition.disabled: FastConditionList([
      FastCondition(
        target: 'switch',
        test: (value, field) => value is bool && value,
      ),
    ]),
  },
),

示例：当开关或复选框被选中时启用文本框

const FastCheckbox(
  name: 'checkbox',
  titleText: 'Enable text field when selected',
),
const FastSwitch(
  name: 'switch',
  titleText: 'Enable text field when selected',
),
FastTextField(
  name: 'text_field',
  enabled: false,
  labelText: 'Just some sample text field',
  conditions: {
    FastCondition.enabled: FastConditionList([
      FastCondition(
        target: 'switch',
        test: (value, field) => value is bool && value,
      ),
      FastCondition(
        target: 'checkbox',
        test: (value, field) => value is bool && value,
      ),
    ]),
  },
),

示例：当开关和复选框都被选中时禁用文本框

const FastCheckbox(
  name: 'checkbox',
  titleText: 'Disable text field when selected',
),
const FastSwitch(
  name: 'switch',
  titleText: 'Disable text field when selected',
),
FastTextField(
  name: 'text_field',
  labelText: 'Just some sample text field',
  conditions: {
    FastCondition.enabled: FastConditionList(
      [
        FastCondition(
          target: 'switch',
          test: (value, field) => value is bool && value,
        ),
        FastCondition(
          target: 'checkbox',
          test: (value, field) => value is bool && value,
        ),
      ],
      match: FastConditionMatch.every,
    ),
  },
),

自定义表单控件

有时你需要添加非标准的控件到表单中。通过继承 FastFormField<T> 并实现 FormFieldBuilder<T>，你可以创建自定义的表单控件。

示例：创建一个生成随机整数的自定义控件

1. 创建继承自 FastFormField<int> 的类

class MyCustomField extends FastFormField<int> {
  const MyCustomField({
    super.builder = myCustomFormFieldBuilder,
    super.key,
    required super.name,
  });

  @override
  MyCustomFieldState createState() => MyCustomFieldState();
}

class MyCustomFieldState extends FastFormFieldState<int> {
  @override
  MyCustomField get widget => super.widget as MyCustomField;
}

2. 实现 FormFieldBuilder<int> 返回自定义控件

Widget myCustomFormFieldBuilder(FormFieldState<int> field) {
  final state = field as MyCustomFieldState;
  final decoration = state.decoration;
  final didChange = state.didChange;
  final value = state.value;

  return InputDecorator(
    decoration: decoration,
    child: Row(
      children: [
        ElevatedButton(
          child: const Text('Create random number'),
          onPressed: () => didChange(Random().nextInt(1 << 32)),
        ),
        if (value is int)
          Padding(
            padding: const EdgeInsets.symmetric(horizontal: 12.0),
            child: Text(value.toString()),
          )
      ],
    ),
  );
}

3. 添加所有支持的超初始化参数

class MyCustomField extends FastFormField<int> {
  const MyCustomField({
    super.builder = myCustomFormFieldBuilder,
    super.decoration,
    super.enabled,
    super.helperText,
    super.initialValue,
    super.key,
    super.labelText,
    required super.name,
    super.onChanged,
    super.onReset,
    super.onSaved,
    super.onTouched,
    super.validator,
  });

  @override
  MyCustomFieldState createState() => MyCustomFieldState();
}

通过以上步骤，你可以轻松创建并使用自定义表单控件。

希望这些内容能帮助你更好地理解和使用 flutter_fast_forms 插件。如果你有任何问题或需要进一步的帮助，请随时提问！