目录
1. 引言
在移动应用和 Web 开发中，自动补全（Autocomplete）是提升用户输入效率的核心功能之一。Flutter 通过 Autocomplete 和 RawAutocomplete 组件为开发者提供了强大的工具集。本文将带你从基础实现到高级优化，全面掌握 Flutter 自动补全功能。
2. Autocomplete 的基本用法
Autocomplete 通过 optionsBuilder 提供建议列表，并使用 onSelected 处理用户的选择。
Autocomplete<String>(
optionsBuilder: (TextEditingValue textEditingValue) {
if (textEditingValue.text.isEmpty) {
return const Iterable<String>.empty();
}
return ['苹果', '香蕉', '橙子', '葡萄']
.where((option) => option.contains(textEditingValue.text));
},
onSelected: (String selection) {
print('你选择了: $selection');
},
)
3. 主要属性
| 属性 | 说明 |
|---|---|
optionsBuilder |
动态生成建议列表（支持异步） |
onSelected |
处理用户选择的回调函数 |
fieldViewBuilder |
自定义输入框的样式 |
optionsViewBuilder |
自定义建议列表的样式 |
示例：
Autocomplete<String>(
optionsBuilder: (TextEditingValue textEditingValue) {
return ['Flutter', 'Dart', 'Android', 'iOS']
.where((option) => option.toLowerCase().contains(textEditingValue.text.toLowerCase()));
},
fieldViewBuilder: (context, textEditingController, focusNode, onFieldSubmitted) {
return TextField(
controller: textEditingController,
focusNode: focusNode,
decoration: InputDecoration(labelText: '搜索技术'),
);
},
)
4. 自定义 Autocomplete 样式
4.1 自定义建议列表样式
Autocomplete<String>(
optionsViewBuilder: (context, onSelected, options) {
return Align(
alignment: Alignment.topLeft,
child: Material(
elevation: 4.0,
child: SizedBox(
height: 200,
child: ListView.builder(
padding: EdgeInsets.all(8.0),
itemCount: options.length,
itemBuilder: (context, index) {
final option = options.elementAt(index);
return ListTile(
title: Text(option),
onTap: () => onSelected(option),
);
},
),
),
),
);
},
)
4.2 复杂数据结构处理
class Product {
final String id;
final String name;
final String category;
Product(this.id, this.name, this.category);
}
class ObjectAutocomplete extends StatelessWidget {
final List<Product> _products = [
Product('1', 'iPhone 14', 'Electronics'),
Product('2', 'MacBook Pro', 'Electronics'),
Product('3', 'Coffee Maker', 'Kitchen'),
];
@override
Widget build(BuildContext context) {
return Autocomplete<Product>(
optionsBuilder: (TextEditingValue value) {
return _products.where((product) =>
product.name.toLowerCase().contains(value.text.toLowerCase())
);
},
displayStringForOption: (Product option) => option.name,
optionsViewBuilder: (context, onSelected, options) {
return Align(
alignment: Alignment.topLeft,
child: Material(
elevation: 4,
child: SizedBox(
height: 200,
child: ListView.builder(
itemCount: options.length,
itemBuilder: (context, index) {
final product = options.elementAt(index);
return ListTile(
title: Text(product.name),
subtitle: Text(product.category),
onTap: () => onSelected(product),
);
},
),
),
),
);
},
);
}
}4.3 异步数据加载与防抖
实现 API 动态加载并优化性能：
class AsyncAutocomplete extends StatefulWidget {
@override
_AsyncAutocompleteState createState() => _AsyncAutocompleteState();
}
class _AsyncAutocompleteState extends State<AsyncAutocomplete> {
final Debouncer _debouncer = Debouncer(milliseconds: 500);
final ApiService _apiService = ApiService();
Future<List<Product>> _fetchSuggestions(String query) async {
if (query.isEmpty) return [];
return _apiService.searchProducts(query);
}
@override
Widget build(BuildContext context) {
return Autocomplete<Product>(
optionsBuilder: (TextEditingValue value) {
_debouncer.run(() => setState(() {}));
return _fetchSuggestions(value.text);
},
optionsViewBuilder: (context, onSelected, options) {
return _buildLoadingIndicator(options);
},
);
}
Widget _buildLoadingIndicator(AsyncSnapshot<List<Product>> snapshot) {
if (snapshot.connectionState == ConnectionState.waiting) {
return const CircularProgressIndicator();
}
// 正常构建列表
}
}
class Debouncer {
final int milliseconds;
Timer? _timer;
Debouncer({required this.milliseconds});
void run(VoidCallback action) {
_timer?.cancel();
_timer = Timer(Duration(milliseconds: milliseconds), action);
}
}4.4 多层级搜索建议
optionsBuilder: (value) async {
final results = await Future.wait([
_localSearch(value.text),
_apiSearch(value.text),
_recentSearches(value.text)
]);
return [...results[0], ...results[1], ...results[2]];
},4.5 输入验证与错误处理
onSelected: (Product selection) {
if (!_validateSelection(selection)) {
_showErrorToast('Invalid selection');
_controller.clear();
return;
}
// 处理有效选择
},5. 结论
Autocomplete 是 Flutter 内置的强大自动补全组件，适用于搜索、地址输入等场景。通过 optionsBuilder 可提供动态建议，结合 fieldViewBuilder 和 optionsViewBuilder 还能自定义 UI 样式，满足不同需求。熟练使用 Autocomplete 可以显著提升应用的交互体验。
相关推荐
Flutter 输入组件 Checkbox 详解-CSDN博客文章浏览阅读724次，点赞26次，收藏10次。在 Flutter 中，Checkbox 是一个常用的多选组件，适用于设置开关选项、同意协议、筛选条件等场景。Checkbox 允许用户勾选或取消勾选，并可通过 value 和 onChanged 进行状态管理。本文将介绍 Checkbox 的基本用法、主要属性及自定义样式。https://shuaici.blog.csdn.net/article/details/146068557Flutter 输入组件 Radio 详解-CSDN博客文章浏览阅读919次，点赞24次，收藏30次。在 Flutter 中，Radio是用于单选的按钮组件，适用于需要用户在多个选项中选择一个的场景，如表单、设置选项等。Radio通过value和groupValue进行状态管理，并结合onChanged监听选中状态的变化。本文将介绍Radio的基本用法、主要属性及自定义样式。
https://shuaici.blog.csdn.net/article/details/146068599