riverpod-refs

Riverpod — Ref

使用方法

Ref（ウィジェットでは WidgetRef）を使って、プロバイダーとやり取りします。状態の読み取り、変更の監視、状態のリセット、ライフサイクルコールバックの登録ができます。プロバイダーには、関数の最初の引数として Ref が渡されるか、Notifier では this.ref として渡されます。ウィジェットでは、Consumer／ConsumerWidget／ConsumerState を通じて WidgetRef を取得します。

Ref の取得

• プロバイダー内： プロバイダー関数の最初の引数、または Notifier の ref プロパティを使います。
• ウィジェット内： Consumer（ビルダーで 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) — プロバイダーの状態が破棄されるときに呼び出されます（例：auto-dispose または再計算時）。StreamController を閉じたり、タイマーをキャンセルしたりするために使用します。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 は複数回呼び出すことができます（例：破棄可能なリソースごとに1回）。onDispose/onCancel の戻り値を呼び出すと、登録を解除できます。詳しい情報や select/listenManual については、reference.md を参照してください。