当前位置：首页 > news >正文

Flutter Autocomplete 从入门到进阶：打造智能输入体验的完整指南

news 来源：原创 2025/5/30 15:28:57

1. 引言

2. Autocomplete 的基本用法

3. 主要属性

4. 自定义 Autocomplete 样式

4.1 自定义建议列表样式

4.2 复杂数据结构处理

4.3 异步数据加载与防抖

4.4 多层级搜索建议

4.5 输入验证与错误处理

5. 结论

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 Autocomplete 从入门到进阶：打造智能输入体验的完整指南

1. 引言

2. Autocomplete 的基本用法

3. 主要属性

4. 自定义 Autocomplete 样式

4.1 自定义建议列表样式

4.2 复杂数据结构处理

4.3 异步数据加载与防抖

4.4 多层级搜索建议

4.5 输入验证与错误处理

5. 结论

相关推荐

相关文章：