跨平台开发 / 系统课时
为搜索关键词创建独立状态
为搜索关键词创建独立状态
搜索页最常见的问题之一,是把“当前结果”放进单个 Provider,导致关键词一变化就覆盖上一组数据。使用 family 后,可以把关键词直接作为 Provider 的参数,让 flutter、riverpod 等查询分别拥有自己的异步状态和缓存边界。
学习目标
- 使用
FutureProvider.family按搜索关键词创建独立结果状态 - 理解切换关键词时为何不会覆盖其他参数对应的缓存
- 判断搜索场景中何时需要配合自动回收
把关键词变成 Provider 参数
普通 FutureProvider 只有一个实例;如果它内部依赖一个可变关键词,所有查询都在争用同一份加载、成功和错误状态。family 的关键变化,是把关键词变成选择 Provider 实例的键。
下面的示例使用本地数据模拟搜索。首次查询某个关键词时会打印日志;切换到其他关键词后再切回来,可以观察同一个关键词对应的状态是否被复用。
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
const products = <String>[
'Flutter 入门',
'Flutter 动画',
'Riverpod 状态管理',
'Riverpod 异步数据',
];
final searchResultsProvider =
FutureProvider.family<List<String>, String>((ref, keyword) async {
final normalized = keyword.trim().toLowerCase();
print('search: $normalized');
await Future<void>.delayed(const Duration(milliseconds: 300));
if (normalized.isEmpty) return const <String>[];
return products
.where((item) => item.toLowerCase().contains(normalized))
.toList();
});
void main() {
runApp(const ProviderScope(child: SearchApp()));
}
class SearchApp extends ConsumerStatefulWidget {
const SearchApp({super.key});
@override
ConsumerState<SearchApp> createState() => _SearchAppState();
}
class _SearchAppState extends ConsumerState<SearchApp> {
final controller = TextEditingController(text: 'flutter');
String keyword = 'flutter';
@override
void dispose() {
controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
final results = ref.watch(searchResultsProvider(keyword));
return MaterialApp(
home: Scaffold(
appBar: AppBar(title: const Text('Search family')),
body: Padding(
padding: const EdgeInsets.all(16),
child: Column(
children: [
TextField(
controller: controller,
onSubmitted: (value) {
setState(() => keyword = value.trim().toLowerCase());
},
),
const SizedBox(height: 16),
results.when(
loading: () => const CircularProgressIndicator(),
error: (error, stackTrace) => Text('Error: $error'),
data: (items) => Text(items.join('\n')),
),
],
),
),
),
);
}
}预期结果
首次进入页面:
search: flutter
页面显示 Flutter 入门、Flutter 动画
提交 riverpod:
search: riverpod
页面显示 Riverpod 状态管理、Riverpod 异步数据
再次提交 flutter:
页面重新显示 Flutter 入门、Flutter 动画
控制台不会再次出现 search: flutter这里没有使用 autoDispose,所以已经读取过的参数实例会在当前 ProviderScope 对应的容器中保留。再次传入相同字符串时,会回到同一个参数对应的 Provider 状态,而不是把 riverpod 的结果改写成 flutter 的结果。

为什么结果不会互相覆盖
可以把 family 理解成“以参数为键的 Provider 集合”。调用 searchResultsProvider('flutter') 与 searchResultsProvider('riverpod') 时,Riverpod 会把它们当作两个独立实例管理,各自拥有自己的 AsyncValue、缓存结果和生命周期。
因此,页面只需要决定“现在要监听哪个参数实例”。关键词改变时,ref.watch 会改为监听新的实例;旧实例的结果并不会被写进新实例,也不需要手工维护 Map<String, List<String>> 来隔离数据。
控制搜索缓存的生命周期
搜索关键词往往是高基数参数:用户可能输入大量只出现一次的字符串。如果长期保留所有实例,缓存会不断增长。此时可以改为 FutureProvider.autoDispose.family,让不再被监听的查询状态具备自动回收能力。
是否使用自动回收取决于产品需求:希望用户返回旧关键词时立即看到缓存,可保留实例或设计明确缓存策略;关键词非常多、结果可快速重取时,优先考虑 autoDispose。无论采用哪种生命周期策略,family 解决的核心问题都不变:每个参数都有独立状态边界。