跨平台开发 / 系统课时
用 family 按 ID 加载详情
用 family 按 ID 加载详情
详情页通常只有一个 Provider 定义,却要根据用户 ID、文章 ID 等参数缓存多份彼此独立的异步状态。本节把 AsyncNotifierProvider 与 family 组合:每个 ID 得到自己的加载、成功和失败状态,同一个 ID 的消费者复用同一份状态,并用自动销毁避免长期保留已经离开的详情实例。
学习目标
- 理解
family如何把参数映射为彼此独立的 Provider 实例。 - 用
AsyncNotifierProvider.autoDispose.family按 ID 异步加载详情。 - 正确选择 family 参数,并能只刷新指定 ID 的详情状态。
family 的核心是“参数也是状态身份”
普通 Provider 可以理解为只有一个固定身份;family 则把参数加入身份。同一个定义调用 userDetailProvider(1) 和 userDetailProvider(2) 时,Riverpod 会维护两份独立状态,因此一个 ID 失败、刷新或被销毁,不需要影响另一个 ID。
family 可以理解为“参数到独立 Provider 状态”的映射;参数需要具备稳定的 == 和 hashCode。整数、字符串这类 ID 天然适合作为参数,详情场景通常还适合配合自动销毁,避免长期保留已经离开的参数实例。

定义按 ID 工作的 AsyncNotifier
不用代码生成时,family 的第三个泛型参数就是参数类型。Notifier 通过构造函数接收该参数并保存为字段,build() 再使用这个 ID 调用仓库。下面示例同时创建 ID 1 和 ID 2 两张详情卡,便于观察它们互不干扰。
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
void main() {
runApp(const ProviderScope(child: MyApp()));
}
class User {
const User({required this.id, required this.name});
final int id;
final String name;
}
class UserRepository {
static const _users = <int, User>{
1: User(id: 1, name: 'Ada'),
2: User(id: 2, name: 'Lin'),
};
Future<User> fetchById(int id) async {
await Future<void>.delayed(const Duration(milliseconds: 500));
final user = _users[id];
if (user == null) {
throw StateError('User $id not found');
}
return user;
}
}
final userRepositoryProvider = Provider<UserRepository>((ref) {
return UserRepository();
});
final userDetailProvider = AsyncNotifierProvider.autoDispose
.family<UserDetailNotifier, User, int>(
UserDetailNotifier.new,
);
class UserDetailNotifier extends AsyncNotifier<User> {
UserDetailNotifier(this.userId);
final int userId;
@override
Future<User> build() {
return ref.read(userRepositoryProvider).fetchById(userId);
}
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return const MaterialApp(home: UserListPage());
}
}
class UserListPage extends StatelessWidget {
const UserListPage({super.key});
@override
Widget build(BuildContext context) {
return const Scaffold(
body: SafeArea(
child: Column(
children: [
UserCard(id: 1),
UserCard(id: 2),
],
),
),
);
}
}
class UserCard extends ConsumerWidget {
const UserCard({super.key, required this.id});
final int id;
@override
Widget build(BuildContext context, WidgetRef ref) {
final userState = ref.watch(userDetailProvider(id));
return Card(
child: Padding(
padding: const EdgeInsets.all(16),
child: userState.when(
data: (user) => Row(
children: [
Expanded(child: Text('ID ${user.id}: ${user.name}')),
IconButton(
onPressed: () {
ref.invalidate(userDetailProvider(id));
},
icon: const Icon(Icons.refresh),
),
],
),
loading: () => Text('Loading user $id...'),
error: (error, stackTrace) => Text('Failed: $error'),
),
),
);
}
}预期结果
启动后先分别显示 Loading user 1... 和 Loading user 2...
约 500 毫秒后显示:
ID 1: Ada
ID 2: Lin
点击 ID 1 卡片的刷新按钮时,只会让 userDetailProvider(1) 重新计算;ID 2 的状态保持独立。读取和刷新时必须带上同一个参数
ref.watch(userDetailProvider(id)) 读取的是当前 ID 对应的状态;要取得 Notifier 或失效缓存,也必须使用同一个 family 调用结果,例如 ref.read(userDetailProvider(id).notifier) 与 ref.invalidate(userDetailProvider(id))。不能只写 userDetailProvider,因为 family 本身还没有确定具体状态身份。
如果两个组件都监听 userDetailProvider(1),它们指向同一个参数实例,而不是各自重新创建一份 ID 1 状态。换成 ID 2 后,则进入另一份独立状态。这也是 family 适合详情页、分页编号、语言代码等参数化数据的原因。
参数类型决定缓存能否稳定命中
ID 使用 int 或 String 最简单。若参数是自定义筛选对象,必须保证相同业务参数拥有一致的相等性与哈希值;否则每次构建一个“看起来相同但实际不相等”的对象,都可能被当成新的 family 实例。
详情页参数还经常随路由变化,因此示例使用 autoDispose.family。当某个 ID 已经没有监听者时,对应实例可以被回收;以后再次进入该 ID 时再重新加载。若业务明确要求长期保留缓存,再根据缓存策略调整生命周期,而不是默认让所有访问过的 ID 永久占用状态。