riverpod-refs

Riverpod — Refs

说明

Ref（以及组件中的 WidgetRef）用于与提供程序交互：读取状态、监听更改、重置状态，以及注册生命周期回调。提供程序会将 Ref 作为其函数的第一个参数，或在 Notifier 中通过 this.ref 获取。组件可通过 Consumer / ConsumerWidget / ConsumerState 获取 WidgetRef。

获取 Ref

• 在提供程序中： 提供程序函数的第一个参数，或 Notifier 中的 ref 属性。
• 在组件中： 使用 Consumer（builder 会提供 ref）、ConsumerWidget（build(context, ref)），或 ConsumerStatefulWidget（state 中有 ref）。如有需要，可将 ref 传递给其他函数。

监听状态

• ref.watch(provider) — 声明式。当提供程序发生变化时，组件/提供程序会重新构建。默认在 build 方法中使用。
• ref.listen(provider, (prev, next) { ... }) — 命令式。当提供程序发生变化时执行副作用（例如显示对话框、导航）。可安全地在 build 中使用；在 initState 中使用时，请改用 ref.listenManual 并管理订阅。

// 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.read(provider) — 获取当前值，但不订阅。用于事件处理程序（例如 onPressed），不要为了“优化”而避免使用 watch。若要选择性地触发重建，请使用 ref.watch(provider.select((value) => ...))。

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

重置状态

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

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

生命周期：onDispose、onCancel

在提供程序内部可以注册回调：

• ref.onDispose(callback) — 提供程序状态销毁时调用（例如自动释放或重新计算时）。可用于关闭 StreamControllers、取消计时器等。请勿在 onDispose 中触发会修改其他提供程序状态的副作用。
• ref.onCancel(callback) — 最后一个监听器移除时调用（在释放之前）。ref.onResume(callback) — 在 onCancel 之后再次添加监听器时调用。

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

可以多次调用 onDispose（例如，为每个可释放资源分别调用一次）。调用 onDispose/onCancel 的返回值即可取消注册。更多关于 select/listenManual 的详情，请参阅 reference.md。