# Flutter AutoComplete Debounce 防抖 ![@programunity Photo shared by programunity on February 06, 2023 taggin](https://files.ducafecat.com/docs/images/2025/11/23/516cbcf5135aae2a8c8373871f557709.jpg) ## 效果

## 前言防抖是指在短时间内无意义的多次操作，然后我们规定单位时间内只处理一次。比如搜索框正在输入，就不应该频繁的去查询处理，控制在500毫秒响应一次查询操作。本文将会说明 AutoComplete 组件的使用以及加入防抖的控制，提示用户交互体验。 ## 代码完整代码详见 github . https://github.com/ducafecat/flutter_develop_tips/tree/main/flutter_application_autocomplete ## 正文 ### Autocomplete 参数 | 参数 | 类型 | 说明 | | ---------------------- | ---- | ------------------ | | optionsBuilder | 函数 | 返回可选列表数据值 | | displayStringForOption | 函数 | 格式化显示字段 | | fieldViewBuilder | 函数 | 输入字段组件 | | onSelected | 函数 | 选中项时 | | optionsViewBuilder | 函数 | 构建下拉列表项 | > 参考 > > https://api.flutter.dev/flutter/material/Autocomplete-class.html ### 准备数据 lib/model.dart ```dart /// 国家数据模型 class Country { const Country({ required this.name, required this.size, }); final String name; final int size; @override String toString() { return '$name ($size)'; } } ``` lib/debounce.dart ```dart class DebouncePage extends StatefulWidget { const DebouncePage({super.key}); @override State createState() => _DebouncePageState(); } ``` ```dart class _DebouncePageState extends State { List countryOptions = [ const Country(name: 'Africa', size: 30370000), const Country(name: 'Asia', size: 44579000), const Country(name: 'Australia', size: 8600000), const Country(name: 'Bulgaria', size: 110879), const Country(name: 'Canada', size: 9984670), const Country(name: 'Denmark', size: 42916), const Country(name: 'Europe', size: 10180000), const Country(name: 'India', size: 3287263), const Country(name: 'North America', size: 24709000), const Country(name: 'South America', size: 17840000), ]; ``` ### 编写 Autocomplete 组件返回可选列表数据值 ```dart Widget _mainView() { return Autocomplete( // 返回可选列表数据值 optionsBuilder: (TextEditingValue textEditingValue) async { debounceValue = textEditingValue.text; return countryOptions .where((Country county) => county.name .toLowerCase() .startsWith(debounceValue.toLowerCase())) .toList(); }, ... ``` ```dart @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar(title: const Text("Autocomplete Getx 防抖")), body: Padding(padding: const EdgeInsets.all(10), child: _mainView()), ); } ``` 格式化显示字段 ```dart displayStringForOption: (Country option) => option.name, ``` 输入字段组件 ```dart fieldViewBuilder: ( BuildContext context, TextEditingController fieldTextEditingController, FocusNode fieldFocusNode, VoidCallback onFieldSubmitted, ) { return TextField( controller: fieldTextEditingController, focusNode: fieldFocusNode, style: const TextStyle( fontWeight: FontWeight.bold, color: Colors.amber, fontSize: 24, ), ); }, ``` 选中项时 ```dart onSelected: (Country selection) { if (kDebugMode) { print('Selected: ${selection.name}'); } }, ``` 构建下拉列表项 ```dart optionsViewBuilder: ( BuildContext context, AutocompleteOnSelected onSelected, Iterable options, ) { return Align( alignment: Alignment.topLeft, child: Material( child: Container( width: 300, color: Colors.cyan, child: ListView.builder( padding: const EdgeInsets.all(10.0), itemCount: options.length, itemBuilder: (BuildContext context, int index) { final Country option = options.elementAt(index); return GestureDetector( onTap: () { onSelected(option); }, child: ListTile( title: Text(option.name, style: const TextStyle(color: Colors.white)), ), ); }, ), ), ), ); }, ``` ### 加入防抖代码 ```dart // 标记是否正在防抖 bool isDebounce = false; // 防抖查询值 String debounceValue = ""; ``` ```dart Widget _mainView() { return Autocomplete( // 返回可选列表数据值 optionsBuilder: (TextEditingValue textEditingValue) async { debounceValue = textEditingValue.text; // 防抖处理 // 防抖状态下直接返回空 List [] if (isDebounce) { return Future.value([]); } else { isDebounce = true; // 设置防抖标志 // 1秒防抖直接返回 FutureOr return Future.delayed(const Duration(seconds: 1), () async { List rows = []; // http 拉取数据 try { rows = await Future.delayed( const Duration(milliseconds: 500), // 延迟 500 毫秒，模拟 http 请求 () => countryOptions .where((Country county) => county.name .toLowerCase() .startsWith(debounceValue.toLowerCase())) .toList()); } finally { isDebounce = false; // 关闭防抖标志 } return rows; }); } }, ``` ### 完整代码 lib/debounce.dart ```dart import 'package:flutter/foundation.dart'; import 'package:flutter/material.dart'; import 'model.dart'; class DebouncePage extends StatefulWidget { const DebouncePage({super.key}); @override State createState() => _DebouncePageState(); } class _DebouncePageState extends State { List countryOptions = [ const Country(name: 'Africa', size: 30370000), const Country(name: 'Asia', size: 44579000), const Country(name: 'Australia', size: 8600000), const Country(name: 'Bulgaria', size: 110879), const Country(name: 'Canada', size: 9984670), const Country(name: 'Denmark', size: 42916), const Country(name: 'Europe', size: 10180000), const Country(name: 'India', size: 3287263), const Country(name: 'North America', size: 24709000), const Country(name: 'South America', size: 17840000), ]; // 标记是否正在防抖 bool isDebounce = false; // 防抖查询值 String debounceValue = ""; Widget _mainView() { return Autocomplete( // 返回可选列表数据值 optionsBuilder: (TextEditingValue textEditingValue) async { debounceValue = textEditingValue.text; // 防抖处理 // 防抖状态下直接返回空 List [] if (isDebounce) { return Future.value([]); } else { isDebounce = true; // 设置防抖标志 // 1秒防抖直接返回 FutureOr return Future.delayed(const Duration(seconds: 1), () async { List rows = []; // http 拉取数据 try { rows = await Future.delayed( const Duration(milliseconds: 500), // 延迟 500 毫秒，模拟 http 请求 () => countryOptions .where((Country county) => county.name .toLowerCase() .startsWith(debounceValue.toLowerCase())) .toList()); } finally { isDebounce = false; // 关闭防抖标志 } return rows; }); } }, // 格式化显示字段 displayStringForOption: (Country option) => option.name, // 输入字段组件 fieldViewBuilder: ( BuildContext context, TextEditingController fieldTextEditingController, FocusNode fieldFocusNode, VoidCallback onFieldSubmitted, ) { return TextField( controller: fieldTextEditingController, focusNode: fieldFocusNode, style: const TextStyle( fontWeight: FontWeight.bold, color: Colors.amber, fontSize: 24, ), ); }, // 选中项时 onSelected: (Country selection) { if (kDebugMode) { print('Selected: ${selection.name}'); } }, // 构建下拉列表项 optionsViewBuilder: ( BuildContext context, AutocompleteOnSelected onSelected, Iterable options, ) { return Align( alignment: Alignment.topLeft, child: Material( child: Container( width: 300, color: Colors.cyan, child: ListView.builder( padding: const EdgeInsets.all(10.0), itemCount: options.length, itemBuilder: (BuildContext context, int index) { final Country option = options.elementAt(index); return GestureDetector( onTap: () { onSelected(option); }, child: ListTile( title: Text(option.name, style: const TextStyle(color: Colors.white)), ), ); }, ), ), ), ); }, ); } @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar(title: const Text("Autocomplete Getx 防抖")), body: Padding(padding: const EdgeInsets.all(10), child: _mainView()), ); } } ``` --- end