跨平台开发 / 系统课时

用 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 天然适合作为参数,详情场景通常还适合配合自动销毁,避免长期保留已经离开的参数实例。

family 按 ID 分离 Provider 状态

定义按 ID 工作的 AsyncNotifier

不用代码生成时,family 的第三个泛型参数就是参数类型。Notifier 通过构造函数接收该参数并保存为字段,build() 再使用这个 ID 调用仓库。下面示例同时创建 ID 1 和 ID 2 两张详情卡,便于观察它们互不干扰。

dart
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'),
        ),
      ),
    );
  }
}

预期结果

text
启动后先分别显示 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 永久占用状态。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 family 按 ID 加载详情

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通