Back to Details

riverpod-family

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Riverpod — Family

Riverpod — Family

Instructions

使用说明

Family lets a single provider have multiple independent states, one per parameter combination (like a Map from parameter to state). Use it for API calls that depend on an ID, query, or page number.
Family 允许单个provider拥有多个独立状态，每个参数组合对应一个状态（类似从参数到状态的映射）。适用于依赖ID、查询条件或页码的API调用场景。

Creating a family (functional)

创建family（函数式）

Add 
.family
and an extra type parameter for the argument. The provider function receives 
(ref, param)
:
dart
final userProvider = FutureProvider.autoDispose.family<User, String>((ref, id) async {
  final dio = Dio();
  final response = await dio.get('https://api.example.com/users/$id');
  return User.fromJson(response.data);
});
With code generation, add parameters to the function; the generated provider accepts arguments: 
userProvider(id)
.
添加
.family
并为参数指定额外的类型参数。provider函数会接收
(ref, param)
参数：
dart
final userProvider = FutureProvider.autoDispose.family<User, String>((ref, id) async {
  final dio = Dio();
  final response = await dio.get('https://api.example.com/users/$id');
  return User.fromJson(response.data);
});
使用代码生成时，将参数添加到函数中；生成的provider可接收参数：
userProvider(id)
。

Creating a family (Notifier)

创建family（Notifier方式）

Use 
NotifierProvider.family
/ 
AsyncNotifierProvider.family
(and 
.autoDispose.family
). The Notifier must have a constructor that stores the parameter:
dart
final userProvider = AsyncNotifierProvider.autoDispose.family<UserNotifier, User, String>(
  UserNotifier.new,
);

class UserNotifier extends AsyncNotifier<User> {
  UserNotifier(this.id);
  final String id;

  @override
  Future<User> build() async {
    final dio = Dio();
    final response = await dio.get('https://api.example.com/users/$id');
    return User.fromJson(response.data);
  }
}
使用
NotifierProvider.family
/ 
AsyncNotifierProvider.family
（以及
.autoDispose.family
）。Notifier必须包含一个用于存储参数的构造函数：
dart
final userProvider = AsyncNotifierProvider.autoDispose.family<UserNotifier, User, String>(
  UserNotifier.new,
);

class UserNotifier extends AsyncNotifier<User> {
  UserNotifier(this.id);
  final String id;

  @override
  Future<User> build() async {
    final dio = Dio();
    final response = await dio.get('https://api.example.com/users/$id');
    return User.fromJson(response.data);
  }
}

Using a family

使用family

Pass the parameter when watching or reading:
dart
final user = ref.watch(userProvider('123'));
final other = ref.watch(userProvider('456'));  // independent state
Parameters must have consistent == and hashCode. Do not use mutable or list/map literals as parameters (e.g. 
ref.watch(myProvider([1,2,3]))
is wrong because 
[1,2,3] != [1,2,3]
). Prefer primitives or custom classes with ==/hashCode. Enable riverpod_lint provider_parameters rule to catch mistakes.
在监听或读取时传入参数：
dart
final user = ref.watch(userProvider('123'));
final other = ref.watch(userProvider('456'));  // independent state
参数必须具备一致的**==和hashCode**实现。请勿使用可变对象或列表/映射字面量作为参数（例如
ref.watch(myProvider([1,2,3]))
是错误的，因为
[1,2,3] != [1,2,3]
）。优先使用基本类型或实现了==/hashCode的自定义类。启用riverpod_lint的provider_parameters规则可捕获此类错误。

Auto-dispose with family

结合family使用autoDispose

Enable auto-dispose when using family so that when the parameter goes out of use (e.g. user navigates away), that parameter's state can be disposed and you avoid unbounded cache growth.
使用family时启用auto-dispose，这样当参数不再被使用（例如用户导航离开）时，该参数对应的状态会被释放，避免缓存无限增长。

Overriding in tests

测试中的重写

  • Override a single parameter: pass the same parameter to the override.
  • Override all parameters: override with a provider that ignores the parameter or returns a fixed value. See riverpod-overrides and the docs for exact syntax.
  • 重写单个参数：为重写传入相同的参数。
  • 重写所有参数：使用忽略参数或返回固定值的provider进行重写。有关确切语法，请参阅riverpod-overrides及官方文档。