riverpod-refs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Riverpod — Refs

Instructions

说明

Ref (and WidgetRef in widgets) is how you interact with providers: read state, listen to changes, reset state, and register lifecycle callbacks. Providers get a

Ref

as the first parameter of their function or as

this.ref

in a Notifier. Widgets get a WidgetRef via Consumer / ConsumerWidget / ConsumerState.

Ref（以及widget中的WidgetRef）是你与providers交互的方式：读取状态、监听变化、重置状态，以及注册生命周期回调。Providers会在其函数的第一个参数中获得

Ref

，或者在Notifier中通过

this.ref

获取。Widgets则通过Consumer / ConsumerWidget / ConsumerState获取WidgetRef。

Obtaining a Ref

获取Ref

Inside a provider: First parameter of the provider function, or
```
ref
```
property in a Notifier.
Inside a widget: Use a Consumer (builder gives
```
ref
```
), ConsumerWidget (
```
build(context, ref)
```
), or ConsumerStatefulWidget (state has
```
ref
```
). Pass
```
ref
```
to other functions if needed.

在provider内部： provider函数的第一个参数，或者Notifier中的
```
ref
```
属性。
在widget内部： 使用Consumer（builder会提供
```
ref
```
）、ConsumerWidget（
```
build(context, ref)
```
）或ConsumerStatefulWidget（state包含
```
ref
```
）。如有需要，可将
```
ref
```
传递给其他函数。

Listening to state

监听状态

ref.watch(provider) — Declarative. Your widget/provider rebuilds when the provider changes. Use this by default in build methods.
ref.listen(provider, (prev, next) { ... }) — Imperative. Run side effects when the provider changes (e.g. show a dialog, navigate). Safe to use in build; for initState use
```
ref.listenManual
```
and manage the subscription.

dart

// In a widget
final tick = ref.watch(tickProvider);
return Text('Tick: $tick');

// Side effect when provider changes
ref.listen(tickProvider, (previous, next) {
  print('Tick changed from $previous to $next');
});

ref.watch(provider) — 声明式。当provider发生变化时，你的widget/provider会重建。默认在build方法中使用此方式。
ref.listen(provider, (prev, next) { ... }) — 命令式。当provider变化时执行副作用（例如显示弹窗、页面导航）。可安全用于build方法；若在initState中使用，需用
```
ref.listenManual
```
并管理订阅。

dart

// 在widget中
final tick = ref.watch(tickProvider);
return Text('Tick: $tick');

// 当provider变化时执行副作用
ref.listen(tickProvider, (previous, next) {
  print('Tick changed from $previous to $next');
});

Reading without listening

读取状态但不监听

ref.read(provider) — Get current value without subscribing. Use in event handlers (e.g. onPressed), not to "optimize" by avoiding watch. For selective rebuilds use
```
ref.watch(provider.select((value) => ...))
```
.

dart

onPressed: () {
  final tick = ref.read(tickProvider);
  print('Current tick: $tick');
}

ref.read(provider) — 获取当前值但不订阅。用于事件处理器（例如onPressed），不要为了“优化”而避免使用watch。如需选择性重建，请使用
```
ref.watch(provider.select((value) => ...))
```
。

dart

onPressed: () {
  final tick = ref.read(tickProvider);
  print('Current tick: $tick');
}

Resetting state

重置状态

ref.invalidate(provider) — Discard current state; provider will recompute on next read. If the provider is listened to, a new state is created.
ref.refresh(provider) — Same as invalidate + read: invalidates and returns the new value. Use when you need the new value immediately.

dart

ref.invalidate(tickProvider);
// or
final newTick = ref.refresh(tickProvider);

ref.invalidate(provider) — 丢弃当前状态；provider会在下次读取时重新计算。如果provider被监听，会创建新的状态。
ref.refresh(provider) — 等同于invalidate + read：失效并返回新值。当你需要立即获取新值时使用。

dart

ref.invalidate(tickProvider);
// 或者
final newTick = ref.refresh(tickProvider);

Lifecycle: onDispose, onCancel

生命周期：onDispose、onCancel

Inside a provider you can register callbacks:

ref.onDispose(callback) — Called when the provider state is destroyed (e.g. auto-dispose or recomputation). Use to close StreamControllers, cancel timers, etc. Do not trigger side effects that modify other providers inside onDispose.
ref.onCancel(callback) — Called when the last listener is removed (before dispose). ref.onResume(callback) — Called when a listener is added again after onCancel.

dart

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

You can call onDispose multiple times (e.g. one per disposable resource). Return value of onDispose/onCancel can be called to unregister. For more detail and select/listenManual, see reference.md.

在provider内部你可以注册回调：

ref.onDispose(callback) — 当provider状态被销毁时调用（例如自动销毁或重新计算）。用于关闭StreamControllers、取消计时器等。不要在onDispose中触发修改其他providers的副作用。
ref.onCancel(callback) — 当最后一个监听器被移除时调用（在销毁之前）。ref.onResume(callback) — 当onCancel之后再次添加监听器时调用。

dart

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

你可以多次调用onDispose（例如每个可销毁资源调用一次）。onDispose/onCancel的返回值可用于取消注册。如需了解更多细节以及select/listenManual的用法，请查看reference.md。