riverpod-auto-dispose

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Riverpod — Automatic disposal

Riverpod — 自动销毁

Instructions

说明

With automatic disposal enabled, Riverpod destroys a provider's state when it has no listeners for one frame. This frees memory and stops work (e.g. network requests) when the provider is no longer used.

启用自动销毁后，当Riverpod的provider在一帧内没有任何监听者时，其状态会被销毁。这能在provider不再被使用时释放内存并停止相关工作（例如网络请求）。

Enabling

启用方式

Code generation: Enabled by default. Disable with
```
@Riverpod(keepAlive: true)
```
.

Manual: Add

isAutoDispose: true

when creating the provider (e.g.

Provider.autoDispose(...)

FutureProvider.autoDispose(...)

dart

// Codegen: disable auto-dispose
@Riverpod(keepAlive: true)
String helloWorld(Ref ref) => 'Hello world!';

// Manual: enable
final helloWorldProvider = Provider<String>(
  isAutoDispose: true,
  (ref) => 'Hello world!',
);

When a provider has parameters (family), enable auto-dispose to avoid caching every parameter combination forever and causing memory leaks.

代码生成： 默认启用。可通过
```
@Riverpod(keepAlive: true)
```
禁用。

手动配置： 创建provider时添加

isAutoDispose: true

（例如

Provider.autoDispose(...)

或

FutureProvider.autoDispose(...)

）。

dart

// 代码生成：禁用自动销毁
@Riverpod(keepAlive: true)
String helloWorld(Ref ref) => 'Hello world!';

// 手动配置：启用自动销毁
final helloWorldProvider = Provider<String>(
  isAutoDispose: true,
  (ref) => 'Hello world!',
);

当provider带有参数（family）时，启用自动销毁可避免永久缓存所有参数组合，从而防止内存泄漏。

When disposal runs

销毁时机

Riverpod counts listeners (from ref.watch, ref.listen, etc.). When the count reaches zero, it waits one frame; if still zero, ref.onCancel runs, then the state is destroyed and ref.onDispose runs.

Riverpod会统计监听者数量（来自ref.watch、ref.listen等）。当数量降至零时，它会等待一帧；如果仍为零，则先执行ref.onCancel，随后销毁状态并执行ref.onDispose。

Reacting to disposal: ref.onDispose

响应销毁：ref.onDispose

dart

final provider = StreamProvider<int>((ref) {
  final controller = StreamController<int>();
  ref.onDispose(controller.close);
  return controller.stream;
});

Do not trigger side effects that modify other providers inside onDispose. You can call onDispose multiple times. Other lifecycles: ref.onCancel (last listener removed), ref.onResume (new listener added after cancel).

注册状态销毁时的回调（例如关闭StreamController）：

dart

final provider = StreamProvider<int>((ref) {
  final controller = StreamController<int>();
  ref.onDispose(controller.close);
  return controller.stream;
});

请勿在onDispose中触发修改其他provider的副作用。你可以多次调用onDispose。其他生命周期方法包括：ref.onCancel（最后一个监听者被移除时）、ref.onResume（取消后新增监听者时）。

Forcing destruction: ref.invalidate

强制销毁：ref.invalidate

From a widget or another provider, call ref.invalidate(provider) to destroy the current state. If the provider is still listened to, it will recompute; otherwise it stays destroyed until read again.

dart

onPressed: () => ref.invalidate(someProvider),

For family providers you can invalidate one parameter combination or all (see riverpod-family and docs).

在widget或其他provider中，调用**ref.invalidate(provider)**可销毁当前状态。如果provider仍被监听，它会重新计算；否则会保持销毁状态，直到再次被读取。

dart

onPressed: () => ref.invalidate(someProvider),

对于family provider，你可以销毁单个参数组合或全部组合（详见riverpod-family及官方文档）。

Keeping state alive: ref.keepAlive

保持状态存活：ref.keepAlive

When auto-dispose is enabled, you can call ref.keepAlive() to prevent disposal until the next recomputation. Use to keep successful results alive while allowing failed or unused state to be disposed. The return value can be called to revert to automatic disposal. If the provider is recomputed, auto-dispose is re-enabled.

启用自动销毁后，你可以调用**ref.keepAlive()**来防止状态被销毁，直到下一次重新计算。适用于保留成功结果，同时允许销毁失败或未使用的状态。其返回值可用于恢复自动销毁行为。如果provider被重新计算，自动销毁会重新启用。

Caching for a duration

按时长缓存

Riverpod does not provide a built-in "cache for X seconds". You can implement it with a Timer and ref.keepAlive, or use ref.onCancel/onResume to dispose after a period of no listeners.

Riverpod没有内置的“缓存X秒”功能。你可以通过Timer和ref.keepAlive实现，或使用ref.onCancel/onResume在无监听一段时间后销毁状态。