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 中，信号、计算信号、效果和异步信号接受 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. 计算信号

• 之前（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 执行副作用

如果你曾在构建过程或 mixin 中执行副作用，请将其迁移到局部的 SignalEffect（或别名 SignalListener）小部件。该小部件可安全管理挂载、didUpdateWidget 和卸载清理生命周期钩子。

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

---

4. 可写计算信号（linkedSignal）

如果你曾使用自定义逻辑将外部更新同步回计算信号，请将其迁移到原生的 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，并自动将 widget 替换为高性能的 SignalStatefulWidget。
• 将位置参数形式的 Watch 和 Watch.builder 实例转换为统一的 SignalBuilder 组件。
• 按需将标准的 StatelessWidget 和 StatefulWidget widget 升级为响应式的 SignalWidget 和 SignalStatefulWidget widget。
• 快速将任意 widget 表达式包装在精准定位的 SignalBuilder 中。