信号

信号是一个高性能的状态管理库，有两个主要目标：

尽可能简化小型到复杂应用程序的业务逻辑编写。无论你的逻辑有多复杂，应用程序的更新都应该保持快速，无需你过多思考。信号在后台自动优化状态更新，以触发最少的必要更新。它们默认是惰性的，并自动跳过没有人监听的信号。
像原生内置原语一样集成到框架中。你不需要任何选择器、包装函数或其他东西。可以直接访问信号，当信号的值改变时，你的组件会自动重新渲染。

阅读公告文章了解更多关于信号解决了哪些问题以及它是如何产生的。

安装：

# 仅核心库
npm install @preact/signals-core
# 如果你使用Preact
npm install @preact/signals
# 如果你使用React
npm install @preact/signals-react
# 如果你使用Svelte
npm install @preact/signals-core

指南 / API

信号库暴露了四个函数，它们是构建任何你能想到的业务逻辑的基本构建块。

`signal(initialValue)`

signal函数创建一个新的信号。信号是一个随时间变化的值的容器。你可以通过访问其.value属性来读取信号的值或订阅值更新。

import { signal } from "@preact/signals-core";

const counter = signal(0);

// 从信号中读取值，打印：0
console.log(counter.value);

// 写入信号
counter.value = 1;

通过设置其.value属性来写入信号。更改信号的值会同步更新依赖于该信号的每个计算值和效果，确保你的应用状态始终保持一致。

`signal.peek()`

在极少数情况下，你有一个效果需要基于前一个值写入另一个信号，但你不希望该效果订阅那个信号，你可以通过signal.peek()读取信号的前一个值。

const counter = signal(0);
const effectCount = signal(0);

effect(() => {
	console.log(counter.value);

	// 每当触发这个效果时，增加`effectCount`。
	// 但我们不希望这个信号对`effectCount`做出反应
	effectCount.value = effectCount.peek() + 1;
});

请注意，你应该只在真正需要时使用signal.peek()。在大多数情况下，通过signal.value读取信号的值是首选方式。

`computed(fn)`

数据经常从其他现有数据派生而来。computed函数让你可以将多个信号的值组合成一个新的信号，这个新信号可以被响应，甚至可以被其他计算值使用。当计算回调函数中访问的信号发生变化时，计算回调会重新执行，其新的返回值成为计算信号的值。

import { signal, computed } from "@preact/signals-core";

const name = signal("Jane");
const surname = signal("Doe");

const fullName = computed(() => name.value + " " + surname.value);

// 打印："Jane Doe"
console.log(fullName.value);

// 更新流经计算值，但只有在有人订阅时才会更新。
// 稍后会详细介绍。
name.value = "John";
// 打印："John Doe"
console.log(fullName.value);

在computed的回调函数内访问的任何信号都会自动被订阅，并作为计算信号的依赖项进行跟踪。

`effect(fn)`

effect函数是使一切变得响应式的最后一块拼图。当你在其回调函数内访问一个信号时，该信号及其所有依赖项都将被激活并订阅。在这方面，它与computed(fn)非常相似。默认情况下，所有更新都是惰性的，所以在你在effect内访问信号之前，什么都不会更新。

import { signal, computed, effect } from "@preact/signals-core";

const name = signal("Jane");
const surname = signal("Doe");
const fullName = computed(() => name.value + " " + surname.value);

// 打印："Jane Doe"
effect(() => console.log(fullName.value));

// 更新其中一个依赖项将自动触发上面的效果，
// 并在控制台打印"John Doe"。
name.value = "John";

你可以通过调用返回的函数来销毁一个效果并取消订阅它所订阅的所有信号。

import { signal, computed, effect } from "@preact/signals-core";

const name = signal("Jane");
const surname = signal("Doe");
const fullName = computed(() => name.value + " " + surname.value);

// 打印："Jane Doe"
const dispose = effect(() => console.log(fullName.value));

// 销毁效果和订阅
dispose();

// 更新不会产生任何效果，因为没有人再订阅了。
// 即使是计算的`fullName`信号也不会改变，因为它知道
// 没有人在监听它。
surname.value = "Doe 2";

效果回调可以返回一个清理函数。清理函数只会运行一次，要么在效果回调下次被调用时，要么在效果被销毁时，以先发生者为准。

import { signal, effect } from "@preact/signals-core";

const count = signal(0);

const dispose = effect(() => {
	const c = count.value;
	return () => console.log(`cleanup ${c}`);
});

// 打印：cleanup 0
count.value = 1;

// 打印：cleanup 1
dispose();

`batch(fn)`

batch函数允许你将多个信号写入操作合并成一个单一的更新，该更新在回调完成时触发。

import { signal, computed, effect, batch } from "@preact/signals-core";

const name = signal("Jane");
const surname = signal("Doe");
const fullName = computed(() => name.value + " " + surname.value);

// 打印："Jane Doe"
effect(() => console.log(fullName.value));

// 将两个信号写入操作合并为一个更新。一旦回调
// 返回，`effect`将触发，我们将打印"Foo Bar"
batch(() => {
	name.value = "Foo";
	surname.value = "Bar";
});

当你在回调内访问一个你先前写入的信号，或访问一个被另一个信号使无效的计算信号时，我们只会更新必要的依赖项以获取你读取的信号的当前值。所有其他无效的信号将在回调函数结束时更新。

import { signal, computed, effect, batch } from "@preact/signals-core";

const counter = signal(0);
const double = computed(() => counter.value * 2);
const triple = computed(() => counter.value * 3);

effect(() => console.log(double.value, triple.value));

batch(() => {
	counter.value = 1;
	// 打印：2，尽管在批处理内，但`triple`
	// 只会在回调完成时更新
	console.log(double.value);
});
// 现在我们到达了批处理的末尾并调用效果

批处理可以嵌套，更新将在最外层的批处理调用完成时刷新。

import { signal, computed, effect, batch } from "@preact/signals-core";

const counter = signal(0);
effect(() => console.log(counter.value));

batch(() => {
	batch(() => {
		// 信号被使无效，但更新不会刷新，因为
		// 我们仍在另一个批处理内
		counter.value = 1;
	});

	// 仍未更新...
});
// 现在回调完成，我们将触发效果。

`untracked(fn)`

如果你接收到一个可以读取某些信号的回调，但你不想订阅它们，你可以使用untracked来防止任何订阅发生。

const counter = signal(0);
const effectCount = signal(0);
const fn = () => effectCount.value + 1;

effect(() => {
	console.log(counter.value);

	// 每当触发这个效果时，运行`fn`得到新值
	effectCount.value = untracked(fn);
});

许可证

MIT，查看LICENSE文件。