Flutter DropDownSearchField 插件的使用

Flutter中的drop_down_search_field插件提供了一个下拉搜索框（autocomplete）小部件，允许用户在输入时显示建议。以下是该插件的详细介绍、特性、安装指南和一些实用的例子。

特性

• 浮层展示：建议以浮动覆盖层的形式出现在其他组件之上。
• 自定义样式：通过构建器函数定制建议外观。
• 交互控制：指定用户点击建议后的操作。
• 文本字段参数支持：支持TextField的所有常规参数，如装饰、自定义TextEditingController和文本样式等。
• 表单字段版本：包含验证和提交特性的FormField版本。
• 高度可配置：调整建议框装饰、加载条、动画、去抖动时间等选项。
• 多选支持：支持选择多个项目。
• 分页建议：支持分页加载建议列表。

安装

请参照pub上的安装说明进行安装。

注意: DropDownSearchField 1.X基于Dart 3.0 (null-safety)，您也可以探索Flutter 2内置的类似行为的新组件。

使用示例

示例1：基本用法

DropDownSearchField(
  textFieldConfiguration: TextFieldConfiguration(
    autofocus: true,
    style: DefaultTextStyle.of(context).style.copyWith(
      fontStyle: FontStyle.italic
    ),
    decoration: InputDecoration(
      border: OutlineInputBorder()
    )
  ),
  suggestionsCallback: (pattern) async {
    return await BackendService.getSuggestions(pattern);
  },
  itemBuilder: (context, suggestion) {
    return ListTile(
      leading: Icon(Icons.shopping_cart),
      title: Text(suggestion['name']),
      subtitle: Text('\$${suggestion['price']}'),
    );
  },
  onSuggestionSelected: (suggestion) {
    Navigator.of(context).push(MaterialPageRoute(
      builder: (context) => ProductPage(product: suggestion)
    ));
  },
)

这段代码展示了如何配置TextField属性，并通过suggestionsCallback获取建议数据。itemBuilder用于构建每个建议项的UI，而onSuggestionSelected则处理用户选择建议后的逻辑。

示例2：作为表单的一部分

final GlobalKey<FormState> _formKey = GlobalKey<FormState>();
final TextEditingController _dropDownSearchController = TextEditingController();
String _selectedFruit;

Form(
  key: this._formKey,
  child: Padding(
    padding: EdgeInsets.all(32.0),
    child: Column(
      children: <Widget>[
        Text('What is your favorite fruit?'),
        DropDownSearchFormField(
          textFieldConfiguration: TextFieldConfiguration(
            controller: this._dropDownSearchController,
            decoration: InputDecoration(
              labelText: 'Fruit'
            )
          ),          
          suggestionsCallback: (pattern) {
            return FruitsService.getSuggestions(pattern);
          },
          itemBuilder: (context, suggestion) {
            return ListTile(
              title: Text(suggestion),
            );
          },
          transitionBuilder: (context, suggestionsBox, controller) {
            return suggestionsBox;
          },
          onSuggestionSelected: (suggestion) {
            this._dropDownSearchController.text = suggestion;
          },
          validator: (value) {
            if (value.isEmpty) {
              return 'Please select a fruit';
            }
          },
          onSaved: (value) => this._selectedFruit = value,
        ),
        SizedBox(height: 10.0,),
        RaisedButton(
          child: Text('Submit'),
          onPressed: () {
            if (this._formKey.currentState.validate()) {
              this._formKey.currentState.save();
              Scaffold.of(context).showSnackBar(SnackBar(
                content: Text('Your Favorite Fruit is ${this._selectedFruit}')
              ));
            }
          },
        )
      ],
    ),
  ),
)

此例子展示了如何将DropDownSearchField集成到Form中，包括验证和保存功能。

自定义布局架构

默认情况下，DropDownSearchField使用ListView来渲染由itemBuilder创建的项。如果指定了layoutArchitecture组件，则会使用此组件代替。例如，可以使用标准的GridView来渲染网格布局：

DropDownSearchField(
    ...,
  layoutArchitecture: (items, scrollContoller) {
        return ListView(
            controller: scrollContoller,
            shrinkWrap: true,
            children: [
              GridView.count(
                physics: const ScrollPhysics(),
                crossAxisCount: 3,
                crossAxisSpacing: 8,
                mainAxisSpacing: 8,
                childAspectRatio: 5 / 5,
                shrinkWrap: true,
                children: items.toList(),
              ),
            ]);
      },
);

动画与对话框问题

放置在带有动画的widget内的DropDownSearchField可能会导致建议框尺寸不正确的问题。需要手动添加SuggestionsBoxController并在动画结束时调整大小。

对于对话框，由于动画延迟问题，建议框有时会显得过小。当前showDialog有150ms的动画持续时间，而DropDownSearchField有一个170ms的延迟补偿。若遇到问题，关闭并重新打开键盘通常能解决问题。

更多功能

除了上述内容外，还有更多关于自定义文本字段、建议框装饰、加载器、错误信息、“无结果”消息、隐藏建议框、调整建议框位置和方向等功能，请参考官方文档获取更多信息。

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