signals-flutter

Flutter Reactive Signals 集成

本技能介绍如何利用 signals_flutter 包优化 Flutter UI 绑定、实现元素级响应式跟踪，以及支持高频渲染。

相关文档与条目

核心原语

相关文件	描述
signal.md	标准可写响应式状态原语，包含值访问器、变更机制和基本自定义选项。
computed.md	惰性、带记忆的只读派生状态信号，可动态跟踪响应式依赖。
effect.md	同步观察器，用于管理活动订阅循环、动态依赖更新和生命周期清理。
readonly.md	只读信号视图，确保数据访问流单向进行。
batch.md	事务式状态变更代码块，可优化响应式计算并避免渲染或重新计算抖动。

异步操作

相关文件	描述
future_signal.md	单次求值的异步 Future 状态表示，可解决重复求值问题。
stream_signal.md	动态且生命周期安全的流监听器，可自行释放，并映射为异步加载、数据和错误状态。
async_signal.md	统一的异步状态容器，可清晰映射加载、成功数据和失败错误状态。
computed_async.md	基于响应式信号构建的可组合异步操作，并提供有效的竞态条件保护。
computed_from.md	状态聚合器信号，可将多个异步信号合并为单一统一结果。

响应式集合

相关文件	描述
list_signal.md	优化的列表包装器，通过代理标准操作支持元素级响应式。
set_signal.md	自定义集合包装器，可忽略重复项，并在唯一变更时发出通知。
map_signal.md	细粒度映射包装器，支持独立触发字典元素查找。
iterable_signal.md	可迭代对象包装器，可将自定义惰性遍历映射到动态订阅层。
queue_signal.md	双端队列包装器，支持优化的响应式流水线结构。

实用原语

相关文件	描述
linked_signal.md	可写的计算信号，支持手动覆盖重置和自定义等价性检查。
tracked_signal.md	状态历史包装器，可直接启用简洁的撤销和重做机制。
timer_signal.md	定时发出信号的秒表，内置暂停、恢复和重置功能。
connect.md	动态事件连接器，可将多个外部数据流水线接入单一目标。

Flutter 组件

相关文件	描述
signal_builder.md	局部子树重建组件，使用命名的 builder 回调签名。
signal_widget.md	组件级响应式无状态/有状态组件，可解决 SignalsMixin 弃用问题。
signal_effect.md	布局安全的副作用协调器，可清晰映射触发事件（如 SnackBar、对话框和路由）。
signal_custom_paint.md	超高性能 GPU 渲染盒，可绕过画布绘制操作，以 120 FPS 运行。

Flutter 扩展

相关文件	描述
watch.md	[已弃用] 旧版上下文级 watch 扩展（建议改用 SignalBuilder 或 SignalWidget）。

核心原语快速入门指南

signals 库提供五个核心函数，它们是构建任意响应式业务逻辑的基础。

1. signal(initialValue)

创建一个新的可变 signal 容器。访问 .value 即可读取 signal 的值或订阅其更新。

final counter = signal(0);
print(counter.value); // 0
counter.value = 1; // Mutates value and schedules dependent updates

.peek()

读取 signal 当前的值，但不会订阅其变更。

final counter = signal(0);
final logCount = signal(0);

effect(() {
  print(counter.value);
  // Read using peek to avoid subscribing/triggering loop
  logCount.value = logCount.peek() + 1;
});

2. untracked(fn)

执行一个回调，在读取 signal 时不会订阅任何 signal。

final counter = signal(0);
final count = signal(0);

effect(() {
  print(counter.value);
  count.value = untracked(() => count.value + 1);
});

3. computed(fn)

将多个 signal 的值组合成一个惰性、带记忆的派生 signal。

final first = signal('John');
final last = signal('Doe');
final fullName = computed(() => '${first.value} ${last.value}');
print(fullName.value); // John Doe

4. effect(fn)

通过运行回调并订阅其中读取的任何 signal，协调立即执行的同步副作用。

final name = signal('Jane');
final dispose = effect(() => print('Hello $name'));
dispose(); // Clean up subscription

5. batch(fn)

将多次 signal 写入合并为一个事务，在事务结束时恰好执行一次所有依赖的计算和副作用。

final a = signal(0);
final b = signal(0);

batch(() {
  a.value = 1;
  b.value = 2;
});

---

1. Widget 重建优化

A. SignalBuilder（首选）

提供局部化、上下文隔离的 widget 重建。仅将尽可能小的 widget 包裹在 SignalBuilder 中，以实现极高的渲染性能。

SignalBuilder(
  builder: (context) => Text('Count: ${counter.value}'),
)

B. 响应式组件 Widget（SignalWidget / SignalStatefulWidget）

在 v7 中，SignalsMixin 和 BuildContext.watch(context) 已弃用（自定义 lint 规则会因此触发警告）。请改为继承 SignalWidget 或 SignalStatefulWidget，而不是使用 mixin 或 context 扩展 watch，以便在标准 widget 树中自动进行高度优化的响应式跟踪：

// Reactive Stateless Widget
class MyWidget extends SignalWidget {
  const MyWidget({super.key});

  @override
  Widget build(BuildContext context) {
    return Text('Count: ${counter.value}');
  }
}

---

2. 高频渲染（SignalCustomPaint）

对于由 signal 驱动的超高频绘制，可完全绕过 Flutter 繁重的 widget 布局／重建生命周期。 SignalCustomPaint 和 SignalPainterWidget 会在自定义代理 render box 中调用 markNeedsPaint()，直接向 GPU 写入内容：

SignalCustomPaint(
  painter: MySignalPainter(progressSignal),
  child: Container(),
)

---

3. Widget 树中的副作用（SignalEffect）

使用 SignalEffect / SignalListener，在 widget 生命周期中简洁地触发异步副作用（例如，显示 snackbar、导航、显示模态框）。

SignalEffect(
  callback: (context) {
    if (errorMessage.value != null) {
      showDialog(context: context, builder: (_) => Alert(errorMessage.value!));
    }
  },
  child: ChildWidget(),
)