signals-migration-6-to-7

signals.dart v6 から v7 への移行

このガイドでは、signals.dart バージョン 6.x を使用するアプリケーションやパッケージを 7.0.0 に移行するための包括的な手順を説明します。

関連ドキュメントと項目

関連ファイル	説明
signal_options.md	signal および computed の作成関数で分散していたパラメーター（例：autoDispose、debugLabel）を、新しい統一オプションクラスに移行するためのガイドです。
async_options.md	非同期シグナル作成関数（futureSignal、streamSignal）を AsyncSignalOptions に移行するためのガイドラインです。
collection_options.md	コレクションベースのシグナル作成関数を、型安全なコレクションオプションクラスに移行する手順です。
builder_migration.md	SignalBuilder コンストラクターで必須の名前付き builder パラメーターを使用するための移行方法です。
mixin_migration.md	非推奨の SignalsMixin を SignalWidget または局所化されたビルダーに置き換える、安全なリファクタリングのガイドラインです。

---

1. 統一オプションクラス（名前付きパラメーターパターン）

v6 では、シグナル、computed、エフェクト、非同期シグナルに、autoDispose、debugLabel、lazy などの個別のパラメーターを渡していました。 v7 では、すべてのパラメーターが単一の統一された options クラスパラメーターにまとめられました。

A. 一般的なシグナル

• 変更前（v6）：

  final count = signal(0, autoDispose: true, debugLabel: 'counter');
  

• 変更後（v7）：

  final count = signal(0, options: SignalOptions(autoDispose: true, name: 'counter'));
  

B. Computed シグナル

• 変更前（v6）：

  final double = computed(() => count.value * 2, autoDispose: true, debugLabel: 'double');
  

• 変更後（v7）：

  final double = computed(() => count.value * 2, options: ComputedOptions(autoDispose: true, name: 'double'));
  

C. コレクションシグナル（listSignal、setSignal、mapSignal など）

すべてのコレクションで、型に対応した統一オプションオブジェクト（例：ListSignalOptions、SetSignalOptions、MapSignalOptions、IterableSignalOptions、QueueSignalOptions）を使用できるようになりました。

• 変更前（v6）：

  final list = listSignal([1, 2], autoDispose: true);
  

• 変更後（v7）：

  final list = listSignal([1, 2], options: ListSignalOptions(autoDispose: true));
  

---

2. 非同期シグナルのリファクタリング

すべての非同期作成関数（futureSignal、streamSignal、asyncSignal、computedFrom、computedAsync）では、値またはコールバックの主要パラメーターに続けて、名前付きの options パラメーター（AsyncSignalOptions）のみを受け取るようになりました。それ以外のパラメーターには @Deprecated が付与されています。

• 変更前（v6）：

  final s = futureSignal(() => fetch(), lazy: false, initialValue: 0);
  

• 変更後（v7）：

  final s = futureSignal(() => fetch(), options: AsyncSignalOptions(lazy: false, initialValue: 0));
  

---

3. Flutter 連携のアップグレード

A. SignalsMixin の非推奨化

状態管理のオーバーヘッドを防ぐため、SignalsMixin は非推奨になりました。代わりに、局所化されたウィジェットまたはビルダーを使用してください。

• 移行方法：
  • State with SignalsMixin を、ステートレスな SignalWidget またはステートフルな SignalStatefulWidget に置き換えます。
  • または、シグナルの更新に依存するウィジェットだけをラップする、局所化された SignalBuilder ウィジェットを使用します。

B. SignalBuilder の名前付き builder パラメーター

SignalBuilder ウィジェットでは、位置引数の代わりに必須の名前付きパラメーター builder を使用するようになりました。

• 変更前（v6）：

  SignalBuilder(
    (context, value) => Text('$value'),
  )
  

• 変更後（v7）：

  SignalBuilder(
    builder: (context, value) => Text('$value'),
  )
  

C. SignalEffect / SignalListener による副作用

ビルド内やミックスイン内で副作用を実行していた場合は、マウント、didUpdateWidget、アンマウント時のティアダウンに関するライフサイクルフックを安全に管理する、局所化された SignalEffect（またはエイリアスの SignalListener）ウィジェットに移行してください。

SignalEffect(
  callback: (context) {
    if (error.value != null) {
      ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(error.value!)));
    }
  },
  child: MyWidget(),
)

---

4. 書き込み可能な Computed シグナル（linkedSignal）

外部からの更新を computed シグナルに同期するカスタムロジックを実装していた場合は、標準の linkedSignal または LinkedSignalOptions に移行してください。

final original = signal('Alice');
final display = linkedSignal(() => original.value);

print(display.value); // 'Alice'
display.value = 'Bob'; // Override manual write
original.value = 'Charlie'; // Source changes -> resets display to 'Charlie'

5. signals_lint による自動リファクタリング

v6 から v7 への移行を完全に手間なく行えるように、signals_lint ツールがコードを分析し、IDE のアクションメニュー（Alt+Enter または Cmd+.）からすぐに適用できる自動クイックフィックス／アシストを提示します。

• 従来の with SignalsMixin を削除し、ウィジェットを高パフォーマンスな SignalStatefulWidget に自動的に置き換えます。
• 位置引数の Watch と Watch.builder のインスタンスを、統一された SignalBuilder コンポーネントに変換します。
• 標準の StatelessWidget と StatefulWidget を、指示ひとつでリアクティブな SignalWidget と SignalStatefulWidget に昇格させます。
• 任意のウィジェット式を、対象を絞った SignalBuilder ですばやくラップします。