跨平台开发 / 系统课时
理解 family 的实例隔离
理解 family 的实例隔离
family 不是在一个 Provider 里存放很多参数,而是根据参数值选择不同的 Provider 实例。理解这一点后,缓存复用、刷新范围和参数设计都会更清楚:相同参数应落到同一状态边界,不同参数则必须彼此隔离。
学习目标
- 建立“family + 参数 = 独立 Provider 实例”的心智模型
- 理解相同参数如何复用状态、不同参数如何形成缓存边界
- 为多字段参数选择具有稳定相等性的值类型
参数决定实例边界
可以把一个 family 看成按参数索引的 Provider 集合。两个组件同时读取完全相同的参数时,它们共享该参数对应的实例;只要参数值不同,就会进入另一份状态与缓存。
下面使用 Dart 记录类型作为复合参数。两个卡片读取相同的 flutter + page 1,第三个卡片读取 flutter + page 2。Provider 每次真正创建计算时都会打印一条日志。
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
typedef SearchArgs = ({String keyword, int page});
final pageProvider =
FutureProvider.family<String, SearchArgs>((ref, args) async {
print('build ${args.keyword}/${args.page}');
await Future<void>.delayed(const Duration(milliseconds: 200));
return '${args.keyword} result page ${args.page}';
});
void main() {
runApp(const ProviderScope(child: DemoApp()));
}
class DemoApp extends ConsumerWidget {
const DemoApp({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
const firstPage = (keyword: 'flutter', page: 1);
const secondPage = (keyword: 'flutter', page: 2);
final a = ref.watch(pageProvider(firstPage));
final b = ref.watch(pageProvider(firstPage));
final c = ref.watch(pageProvider(secondPage));
String textOf(AsyncValue<String> value) {
return value.when(
loading: () => 'loading',
error: (error, stackTrace) => 'error: $error',
data: (data) => data,
);
}
return MaterialApp(
home: Scaffold(
body: Center(
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
Text('A: ${textOf(a)}'),
Text('B: ${textOf(b)}'),
Text('C: ${textOf(c)}'),
],
),
),
),
);
}
}预期结果
控制台只会为两个不同参数建立计算:
build flutter/1
build flutter/2
页面最终显示:
A: flutter result page 1
B: flutter result page 1
C: flutter result page 2A 与 B 使用相同参数,因此共享同一个参数实例;C 的页码不同,因此拥有另一份状态。这里的隔离边界由完整参数值决定,而不是只看 keyword 字段。

相同参数为什么必须“相等”
family 依赖参数的 == 与 hashCode 来判断两次调用是否属于同一个键。如果参数看起来内容相同,但每次比较都不相等,Riverpod 就无法稳定复用对应实例,缓存也会被拆成多份。
字符串、数字以及 Dart 记录类型都很适合作为参数。记录会按字段值比较,因此 (keyword: 'flutter', page: 1) 在多次构造时仍能表达同一个键。若改用自定义类,应保证对象不可变,并正确实现值相等与 hashCode。
刷新也应落在具体实例上
实例隔离不仅影响读取,也影响刷新范围。用户只想重试某个查询时,应针对那组参数对应的 Provider 实例进行失效处理,而不是把所有查询状态一起清空。
例如当前参数保存在 args 变量中时,可以调用 ref.invalidate(pageProvider(args))。这会让该参数对应的实例失效;其他参数实例仍保持自己的状态。于是 family 的实际边界可以总结为:参数负责选实例,实例负责持有状态,生命周期操作也应尽量针对同一个参数边界。