signals-preact-dart

Dart 中的 Preact Signals

本技能介绍 preact_signals 包的核心响应式编程原语和实现模式。

相关文档与条目

相关文件	描述
signal.md	标准的可写响应式状态原语，包含值访问器、变更机制和基本自定义选项。
computed.md	惰性、记忆化的只读派生状态信号，可动态跟踪响应式依赖。
effect.md	同步观察器，用于管理活动订阅循环、动态依赖更新和生命周期拆除。
readonly.md	只读信号视图，确保数据访问流向单一。
batch.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)

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

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

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

---

1. 核心原语详解

A. Signal<T>

一种表示可观察的可变值的状态原语。

final count = signal(0);
count.value = 1; // Notifies all active subscribers/effects

B. Computed<T>

一种派生状态原语，表示根据其他信号计算得出的只读值。它具有以下特性：

• 惰性：仅在访问时计算。
• 记忆化：缓存其值，仅在源依赖项发生变化时重新计算。

final count = signal(2);
final double = computed(() => count.value * 2);

C. Effect

一种观察器，会立即执行回调并跟踪读取的信号。每当任何已跟踪的信号发生变化时，它都会重新运行。

final dispose = effect(() {
  print('Current count: ${count.value}');
});
dispose(); // Clean up subscription

---

2. 依赖跟踪与重入规则

• 同步上下文：根据回调执行期间读取的信号，动态跟踪依赖项。
• 循环检测：在 computed 信号自身的执行流程中读取该信号，或在 computed 回调中设置依赖项，都会导致循环。避免在 computed getter 中产生副作用。
• 惰性初始值：创建惰性 computed 信号时不会对其求值。在观察器中强制调用 .peek() 前，务必先调用 isInitialized 或检查初始化状态，以避免因重入循环而崩溃。