Flutter自动完成表单字段插件efficient_autocomplete_formfield的使用

efficient_autocomplete_formfield 是一个 Flutter 插件，用于在表单中实现自动完成功能。它可以帮助用户在输入时自动匹配和选择预先定义的选项，提升用户体验。以下是如何使用 efficient_autocomplete_formfield 插件的详细步骤。

1. 添加依赖

首先，在 pubspec.yaml 文件中添加 efficient_autocomplete_formfield 插件的依赖：

dependencies:
  flutter:
    sdk: flutter
  efficient_autocomplete_formfield: ^1.0.0  # 请检查最新版本

然后运行 flutter pub get 来安装依赖。

2. 基本用法

以下是一个简单的示例，展示如何使用 efficient_autocomplete_formfield 插件。

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

class AutocompleteFormFieldExample extends StatefulWidget {
  @override
  _AutocompleteFormFieldExampleState createState() => _AutocompleteFormFieldExampleState();
}

class _AutocompleteFormFieldExampleState extends State<AutocompleteFormFieldExample> {
  final _formKey = GlobalKey<FormState>();
  String? _selectedItem;

  // 预定义的选项
  final List<String> _options = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry', 'Fig', 'Grape'];

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Autocomplete FormField Example'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Form(
          key: _formKey,
          child: Column(
            children: [
              EfficientAutocompleteFormField(
                suggestions: _options,
                onChanged: (value) {
                  setState(() {
                    _selectedItem = value;
                  });
                },
                decoration: InputDecoration(
                  labelText: 'Select a fruit',
                  border: OutlineInputBorder(),
                ),
                validator: (value) {
                  if (value == null || value.isEmpty) {
                    return 'Please select a fruit';
                  }
                  return null;
                },
              ),
              SizedBox(height: 20),
              ElevatedButton(
                onPressed: () {
                  if (_formKey.currentState!.validate()) {
                    // 表单验证通过后的操作
                    ScaffoldMessenger.of(context).showSnackBar(
                      SnackBar(content: Text('Selected: $_selectedItem')),
                    );
                  }
                },
                child: Text('Submit'),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

void main() {
  runApp(MaterialApp(
    home: AutocompleteFormFieldExample(),
  ));
}

3. 参数说明

• suggestions: 预定义的选项列表，通常是字符串列表。
• onChanged: 当用户选择或输入内容时触发的回调函数。
• decoration: 用于自定义输入框的外观，比如标签、边框等。
• validator: 用于表单验证的回调函数，返回 null 表示验证通过，否则返回错误信息。

4. 自定义选项显示

如果你想自定义选项的显示方式，可以使用 itemBuilder 参数。例如，你可以为每个选项添加图标或其他小部件：

EfficientAutocompleteFormField(
  suggestions: _options,
  itemBuilder: (context, suggestion) {
    return ListTile(
      leading: Icon(Icons.food_bank),
      title: Text(suggestion),
    );
  },
  onChanged: (value) {
    setState(() {
      _selectedItem = value;
    });
  },
  decoration: InputDecoration(
    labelText: 'Select a fruit',
    border: OutlineInputBorder(),
  ),
  validator: (value) {
    if (value == null || value.isEmpty) {
      return 'Please select a fruit';
    }
    return null;
  },
);

5. 处理异步数据

如果你的选项数据是异步获取的（例如，从 API 或数据库中获取），你可以使用 FutureBuilder 或其他异步处理方式来动态加载数据。

EfficientAutocompleteFormField(
  suggestions: _futureOptions,  // _futureOptions 是一个 Future<List<String>>
  onChanged: (value) {
    setState(() {
      _selectedItem = value;
    });
  },
  decoration: InputDecoration(
    labelText: 'Select a fruit',
    border: OutlineInputBorder(),
  ),
  validator: (value) {
    if (value == null || value.isEmpty) {
      return 'Please select a fruit';
    }
    return null;
  },
);

6. 其他功能

efficient_autocomplete_formfield 还支持其他一些功能，例如：

• 禁用自动完成：通过 enabled 参数可以禁用自动完成功能。
• 自定义过滤器：通过 filter 参数可以自定义选项的过滤逻辑。
• 键盘动作：通过 textInputAction 参数可以控制键盘的动作按钮。

7. 处理复杂的对象

如果你的选项是复杂的对象而不是简单的字符串，你可以使用 displayStringForOption 参数来指定如何显示对象的字符串表示。

EfficientAutocompleteFormField<MyCustomObject>(
  suggestions: _customObjects,
  displayStringForOption: (MyCustomObject option) => option.name,
  onChanged: (value) {
    setState(() {
      _selectedCustomObject = value;
    });
  },
  decoration: InputDecoration(
    labelText: 'Select a custom object',
    border: OutlineInputBorder(),
  ),
  validator: (value) {
    if (value == null) {
      return 'Please select a custom object';
    }
    return null;
  },
);