riverpod-3-0-migration

Riverpod — 2.0 から 3.0 への移行

変更点と主な特徴の全リストについては、Riverpod の公式ドキュメント（Riverpod 3.0 の新機能）を参照してください。このスキルでは、主な移行手順をまとめています。

自動リトライ

3.0 では、失敗したプロバイダーはデフォルトでリトライされます。これをグローバルに無効にするには、次のようにします。

ProviderScope(retry: (retryCount, error) => null, child: MyApp())
// or ProviderContainer(retry: (retryCount, error) => null)

プロバイダーごとに無効にするには、プロバイダーの定義時に retry: (retryCount, error) => null を渡します（コード生成を使用する場合は @Riverpod(retry: ...)）。riverpod-retry を参照してください。

表示範囲外のプロバイダーは一時停止されます

表示されていないウィジェット（画面外など）のリスナーは、デフォルトで一時停止されます。グローバルな切り替え設定はありません。サブツリーが一時停止されないようにするには、TickerMode(enabled: true, child: ...) で囲み、その内部の Consumer が一時停止の動作に従わないようにします。

レガシープロバイダー（StateProvider、StateNotifierProvider、ChangeNotifierProvider）

これらはレガシーインポートに移動しました。削除されたわけではありませんが、使用は推奨されません。引き続き使用するには、次のようにします。

import 'package:flutter_riverpod/legacy.dart';
// or hooks_riverpod/legacy.dart, riverpod/legacy.dart

更新の判定には == を使用します

すべてのプロバイダーが更新のフィルタリングに == を使用するようになりました（identical は使用されなくなりました）。StreamProvider／StreamNotifier の値は == で比較されます。カスタマイズするには、Notifier の updateShouldNotify(previous, next) をオーバーライドします（たとえば、常に通知するには true を返します）。

ProviderObserver API の変更

オブザーバーメソッドは、個別の（provider、value、container）パラメーターではなく、単一の ProviderObserverContext（container、provider、任意の mutation を含む）を受け取るようになりました。シグネチャを次のように更新してください。

• didAddProvider(ProviderObserverContext context, Object? value)（ほかのコールバックも同様です）。

Ref の簡素化、Ref のサブクラスの削除

• Ref から型パラメーターがなくなりました。どこでも Ref を使用してください（たとえば、コード生成で MyProviderRef を Ref に置き換えます）。
• ProviderRef.state、Ref.listenSelf、FutureProviderRef.future は Notifier／AsyncNotifier に移動しました。ref ではなく、Notifier.state、Notifier.listenSelf、AsyncNotifier.future を使用してください。これらが必要な場合は、クラスベースの Notifier／AsyncNotifier を使用し、notifier で呼び出します。

AutoDispose の型名の削除

AutoDispose は引き続きサポートされますが、個別の型名（AutoDisposeProvider、AutoDisposeNotifier など）は統合されました。同じ動作をする Provider、Notifier などを使用してください。移行時は、型名に含まれる AutoDispose を空文字列に置き換えてください。大文字と小文字は区別されます。

Family Notifier の型の削除

FamilyNotifier、FamilyAsyncNotifier、FamilyStreamNotifier は削除されました。Notifier／AsyncNotifier／StreamNotifier を使用し、パラメーターはコンストラクターに渡してください（フィールドに保存します）。build からパラメーターを削除してください。build() は family 引数を受け取りません。例：

• 変更前：FamilyNotifier<int, String> で int build(String arg) を使用。
• 変更後：コンストラクター MyNotifier(this.arg) と final String arg; を持つ Notifier<int> を使用し、int build() で arg を使用。

ProviderException

プロバイダーが例外をスローすると、その例外は ProviderException にラップされます。元の型（たとえば on NotFoundException）をキャッチしている場合は、on ProviderException catch (e) に変更し、e.exception is NotFoundException を確認してください。AsyncValue と value.hasError／value.error だけを使用している場合は、変更不要です。

まとめ

• リトライ：スコープ／コンテナーまたはプロバイダーで retry を使って無効にします。
• 一時停止：一時停止を避けたい場所では TickerMode(enabled: true) を使用します。
• レガシー：StateProvider／StateNotifierProvider／ChangeNotifierProvider には flutter_riverpod/legacy.dart（または同等のもの）を使用します。
• Ref：通常の Ref を使用し、state／listenSelf／future は Notifier／AsyncNotifier に移します。
• AutoDispose：型名から「AutoDispose」を削除します。
• Family Notifier：コンストラクター引数を使う Notifier／AsyncNotifier を使用します。build() にパラメーターはありません。
• エラー：元の型が必要な場合は ProviderException をキャッチし、exception を調べます。

バージョンの主な変更点と詳細については、Riverpod の公式ドキュメントを参照してください。