riverpod

ref.watch は購読して再ビルドし、ref.read は一度読むだけで再ビルドしません。watch はすべての build メソッドの中で、read はイベントのコールバックの中だけで使います。判断マトリクス、flutter_riverpod 3.4.3 における両メソッドのソースコード、そして 4 つの静かな失敗パターン (コールバック内の watch、プロバイダー本体での read、autoDispose なプロバイダーへの read、最適化のつもりの read) を解説します。

選択は build() の戻り値の型で決まります。T なら Notifier、FutureOr<T> なら AsyncNotifier、Stream<T> なら StreamNotifier です。判断のための比較表、その理由となる型階層、そして == によるフィルタリングと状態の上書きという落とし穴を解説します。flutter_riverpod 3.4.2 と Flutter 3.44.2 で検証済みです。

ウィジェットローカルな setState から Riverpod 3.x の Notifier へ移す手順です。何をウィジェットの外に出すかを仕分けし、Notifier を書き、ConsumerWidget に変換し、setState からの移行者を悩ませる == によるフィルタリング、build() の再実行、autoDispose の既定値の違いを乗り切ります。Flutter 3.44、Dart 3.x、flutter_riverpod 3.3.2 で検証しました。

ほぼすべての Flutter アプリには flutter_riverpod をインストールします。riverpod は純粋な Dart コードのみ、hooks_riverpod は既に flutter_hooks を使っている場合のみ使用します。

Riverpod 3.0 では、すべてのプロバイダーがリスナー通知を同一性ではなく == でフィルタリングします。同じミュータブルオブジェクトを再度発行する StreamProvider は、最初のフレーム以降 UI を再構築しなくなります。なぜそうなるのか、そして 3 つの修正方法を解説します。flutter_riverpod 3.3.2、Flutter 3.44、Dart 3.x で検証済みです。

Riverpod 3.0 はデフォルトで失敗したプロバイダーを最大 10 回リトライします。null を返す retry 関数を ProviderScope、ProviderContainer、または個々のプロバイダーに渡すことで、無効化したり回数を制限したりできます。

flutter_riverpod 2.x から 3.x への段階的なアップグレード手順です。パッケージを更新し、StateProvider などを legacy インポートへ移し、AutoDispose と Family の ref 型を廃止し、ProviderException のラップと自動リトライに対応し、StreamProvider のイベントを暗黙的に取りこぼす == による通知フィルタリングを修正します。Flutter 3.44、Dart 3.x、flutter_riverpod 3.3.2 で検証済みです。

Riverpod 3.0 はプロバイダーの読み取り中にスローされたエラーを ProviderException でラップします。その型をキャッチして e.exception を読めば元のエラーを取り戻せます。あるいは、ラップされない AsyncValue.error を使いましょう。

Notifier では await の前に依存関係を解決し、その後 if (!ref.mounted) return で state の書き込みを保護します。これは Riverpod 3.0 における古い onDispose ミックスインの代替であり、provider が await の途中で破棄されたときの UnmountedRefException を防ぎます。flutter_riverpod 3.x、Flutter 3.44、Dart 3.x で検証済みです。

FutureBuilder を Riverpod 3 AsyncNotifier へ移行。検証済み手動 family、明示的なキャッシュ寿命と再試行、安全な更新処理を解説します。