signals-dart

Signals Core 高级原语

本技能详细介绍 signals_core 中的高级状态管理原语、响应式集合、异步功能和值选项语义。

相关文档与条目

核心原语

相关文件	描述
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	自定义 Set 包装器，可忽略重复项，并在新增唯一元素时通知。
map_signal.md	细粒度 Map 包装器，支持独立触发字典元素查找。
iterable_signal.md	可迭代对象包装器，可将自定义的惰性遍历映射到动态订阅层。
queue_signal.md	双端队列包装器，支持优化的响应式管线结构。

实用原语

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

---

核心原语快速入门指南

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

1. signal(initialValue)

创建一个新的可变信号容器。通过访问 .value 读取信号的值或订阅更新。

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

.peek()

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

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)

执行一个回调，读取信号但不订阅任何信号。

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

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

3. computed(fn)

将多个信号的值组合为一个懒加载、记忆化的派生信号。

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

4. effect(fn)

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

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

5. batch(fn)

将多次信号写入合并为一个事务，在最后只执行一次所有依赖的计算信号求值和副作用。

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

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

---

1. 可写计算信号（linkedSignal）

可写计算信号（LinkedSignal）提供一个派生默认值，可手动覆盖；每当上游依赖项发生变化时，都会重置为派生默认值。

用法

// Basic reset shorthand:
final size = signal('M');
final selection = linkedSignal(() => size.value);

// Advanced structural comparison:
final user = signal((id: 1, name: 'Alice'));
final name = linkedSignal<String, ({int id, String name})>(
  () => user.value,
  options: LinkedSignalOptions(
    computation: (u, prev) {
      if (prev != null && prev.source.id == u.id) {
        return prev.value; // Retain manual override
      }
      return u.name; // Reset on ID changes
    },
  ),
);

---

2. 集合与异步原语

A. 集合

始终使用专用集合（listSignal、setSignal、mapSignal 等）包装集合，以确保执行优化的变更操作（只有元素实际发生变化时才触发更新）。

final list = listSignal([1, 2], options: ListSignalOptions(autoDispose: true));
list.add(3); // Reacts to changes

B. 优化的 FutureSignal

FutureSignal 直接继承自 AsyncSignal，以绕过 Stream 订阅开销，并通过计算执行手动跟踪其依赖项，使 Future 计算恰好执行一次（避免双重求值循环）。

final search = signal('');
final results = futureSignal(() => fetchResults(search.value));

---

3. 选项类的值语义

所有信号选项对象均支持完整的值语义（copyWith、自定义相等性和 hashCode 覆写），便于灵活复制并进行准确比较：

• SignalOptions
• ComputedOptions
• AsyncSignalOptions
• LinkedSignalOptions
• ListSignalOptions / SetSignalOptions / MapSignalOptions