Flutter表单构建扩展字段插件form_builder_extra_fields的使用

简介

form_builder_extra_fields 是一个为 flutter_form_builder 包提供额外输入组件的Flutter包。它使得在表单中添加常见的预构建输入字段变得简单，而无需从头创建自己的 FormBuilderField。

特性

• 为 flutter_form_builder 添加多种类型的输入组件。
• 支持以下输入组件：
  • FormBuilderColorPicker：颜色选择器
  • FormBuilderRating：评分选择
  • FormBuilderSearchableDropdown：可搜索的下拉菜单
  • FormBuilderSignaturePad：签名板
  • FormBuilderTouchSpin：通过点击加减图标来选择数值
  • FormBuilderTypeAhead：自动完成用户输入（如联想输入）

参数

所有类型的输入组件都支持以下通用属性：

使用方法

设置

安装依赖后即可直接使用，无需特别配置。

基本用法

下面是一个简单的示例代码，演示了如何在表单中使用 FormBuilderColorPickerField 组件：

final _formKey = GlobalKey<FormBuilderState>();

FormBuilder(
  key: _formKey,
  child: FormBuilderColorPickerField(
    name: 'color_picker',
  ),
)

示例Demo

这里提供了一个完整的示例应用程序，展示了如何集成多个来自 form_builder_extra_fields 的组件：

import 'package:flutter/material.dart';
import 'package:flutter_form_builder/flutter_form_builder.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:form_builder_extra_fields/form_builder_extra_fields.dart';
import 'package:form_builder_validators/form_builder_validators.dart';

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

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(primarySwatch: Colors.blue),
      localizationsDelegates: const [
        FormBuilderLocalizations.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
      ],
      supportedLocales: const [Locale('en')],
      home: const MyHomePage(),
    );
  }
}

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

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

class MyHomePageState extends State<MyHomePage> {
  final _formKey = GlobalKey<FormBuilderState>();

  void _onChanged(dynamic val) => debugPrint(val.toString());

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Extra Fields Example')),
      body: SingleChildScrollView(
        child: Padding(
          padding: const EdgeInsets.all(8.0),
          child: FormBuilder(
            key: _formKey,
            onChanged: () {
              _formKey.currentState?.save();
              debugPrint(_formKey.currentState?.value.toString());
            },
            autovalidateMode: AutovalidateMode.onUserInteraction,
            child: Column(
              children: [
                // 可搜索的在线下拉菜单
                FormBuilderSearchableDropdown<String>(
                  name: 'searchable_dropdown_online',
                  onChanged: _onChanged,
                  asyncItems: (filter) async {
                    await Future.delayed(const Duration(seconds: 1));
                    return allCountries
                        .where((element) =>
                            element.toLowerCase().contains(filter.toLowerCase()))
                        .toList();
                  },
                  decoration: const InputDecoration(
                    labelText: 'Searchable Dropdown Online',
                  ),
                ),
                // 可搜索的离线下拉菜单
                FormBuilderSearchableDropdown<String>(
                  popupProps: const PopupProps.menu(showSearchBox: true),
                  dropdownSearchDecoration: const InputDecoration(
                    hintText: 'Search',
                    labelText: 'Search',
                  ),
                  name: 'searchable_dropdown_offline',
                  items: allCountries,
                  onChanged: _onChanged,
                  decoration: const InputDecoration(labelText: 'Searchable Dropdown Offline'),
                  filterFn: (country, filter) =>
                      country.toLowerCase().contains(filter.toLowerCase()),
                ),
                const SizedBox(height: 15),
                // 颜色选择器
                FormBuilderColorPickerField(
                  name: 'color_picker',
                  initialValue: Colors.yellow,
                  colorPickerType: ColorPickerType.materialPicker,
                  decoration: const InputDecoration(labelText: 'Color Picker'),
                ),
                // 自动补全文本框
                FormBuilderTypeAhead<String>(
                  decoration: const InputDecoration(
                    labelText: 'TypeAhead (Autocomplete TextField)',
                    hintText: 'Start typing country name',
                  ),
                  name: 'country',
                  onChanged: _onChanged,
                  itemBuilder: (context, country) {
                    return ListTile(title: Text(country));
                  },
                  initialValue: 'Uganda',
                  suggestionsCallback: (query) {
                    if (query.isNotEmpty) {
                      var lowercaseQuery = query.toLowerCase();
                      return allCountries.where((country) {
                        return country.toLowerCase().contains(lowercaseQuery);
                      }).toList(growable: false)
                        ..sort((a, b) => a
                            .toLowerCase()
                            .indexOf(lowercaseQuery)
                            .compareTo(
                                b.toLowerCase().indexOf(lowercaseQuery)));
                    } else {
                      return allCountries;
                    }
                  },
                ),
                // 数字增减控件
                FormBuilderTouchSpin(
                  decoration: const InputDecoration(labelText: 'TouchSpin'),
                  name: 'touch_spin',
                  initialValue: 10,
                  step: 1,
                  iconSize: 48.0,
                  addIcon: const Icon(Icons.arrow_right),
                  subtractIcon: const Icon(Icons.arrow_left),
                  onChanged: _onChanged,
                ),
                // 评分条
                FormBuilderRatingBar(
                  decoration: const InputDecoration(labelText: 'Rating Bar'),
                  name: 'rate',
                  itemSize: 32.0,
                  initialValue: 1.0,
                  maxRating: 5.0,
                  onChanged: _onChanged,
                ),
                // 签名板
                FormBuilderSignaturePad(
                  decoration: const InputDecoration(
                    labelText: 'Signature Pad',
                  ),
                  name: 'signature',
                  border: Border.all(color: Colors.green),
                  onChanged: _onChanged,
                ),
                const SizedBox(height: 10),
                Row(
                  children: <Widget>[
                    Expanded(
                      child: ElevatedButton(
                        onPressed: () {
                          if (_formKey.currentState?.saveAndValidate() ??
                              false) {
                            debugPrint(_formKey.currentState?.value.toString());
                          } else {
                            debugPrint(_formKey.currentState?.value.toString());
                            debugPrint('validation failed');
                          }
                        },
                        child: const Text('Submit'),
                      ),
                    ),
                    const SizedBox(width: 20),
                    Expanded(
                      child: OutlinedButton(
                        onPressed: () {
                          _formKey.currentState?.reset();
                        },
                        child: const Text('Reset'),
                      ),
                    ),
                  ],
                ),
              ],
            ),
          ),
        ),
      ),
    );
  }
}

// 国家列表
const allCountries = [
  'Afghanistan', 'Albania', 'Algeria', /* ... */ 'Zimbabwe'
];

此代码段包括了不同类型的输入组件，并展示了如何将它们组合成一个完整的表单。每个组件都有其特定的功能，如颜色选择、评分、搜索选择等。此外，还提供了提交和重置按钮用于操作整个表单的数据。