最近在技术社区看到不少关于 Amper 的讨论尤其是 Joffrey Bion 分享的《The State of Amper》一文引发了很多开发者对现代前端状态管理方案的重新思考。在 React、Vue 等框架生态日益复杂的今天如何选择一个既轻量又强大、既能应对简单场景又能支撑复杂应用的状态管理库成为了一个高频痛点。本文将深入解析 Amper 的设计理念、核心特性并通过一个完整的实战项目带你从零搭建一个使用 Amper 进行状态管理的现代前端应用。无论你是正在为下一个项目选型纠结的团队负责人还是希望提升技术视野的进阶开发者这篇文章都将提供一套可落地的参考方案。1. Amper 是什么重新理解状态管理在深入代码之前我们有必要厘清 Amper 究竟解决了什么问题以及它与其他流行方案如 Redux, Zustand, Valtio, Jotai的核心差异。1.1 状态管理的核心挑战现代前端应用的状态管理远不止是“存储一个变量”那么简单。它需要处理数据流清晰性状态如何变化变化如何触发 UI 更新这个流程必须可预测、易追踪。组件通信深层嵌套组件间如何高效共享状态避免“prop drilling”。派生状态如何从基础状态计算衍生数据并保持高效更新。副作用管理异步操作如 API 调用如何与状态变更安全、有序地结合。开发者体验代码是否简洁类型提示是否完善调试工具是否强大。1.2 Amper 的设计哲学Amper 由 Joffrey Bion 创建其核心理念是“响应式 原子化”。它并非一个庞大的框架而是一组用于创建响应式数据单元称为“信号”或“原子”和派生状态的原语。它的特点包括极简 API核心概念很少学习曲线平缓。细粒度响应只有真正依赖某个状态的组件才会在该状态变化时重新渲染性能开销极小。不可变与可变性的平衡鼓励不可变更新以保持可预测性但在底层使用可变引用以实现高效更新。框架无关性核心逻辑不依赖任何 UI 框架通过适配器可与 React、Vue、Solid 等集成。出色的 TypeScript 支持提供完整的类型推断开发体验流畅。1.3 与其他方案的对比为了更直观地理解 Amper 的定位我们将其与几个主流方案进行简要对比特性AmperRedux ToolkitZustandValtioJotai心智模型响应式原子单向数据流可变 Store可变代理原子化样板代码极少中等少极少少渲染优化自动细粒度需useSelector优化需手动选择状态自动细粒度自动细粒度异步处理原生支持通过createAsyncThunk在 action 中处理在 action 中处理在 atom 中处理调试工具社区提供官方强大官方提供官方提供官方提供适用场景中到大型应用追求极致性能大型应用需要严格流程中小型应用快速开发中小型应用偏好可变语法原子化需求强的应用Amper 在“简洁性”和“性能”之间找到了一个很好的平衡点特别适合那些觉得 Redux 太重但又需要比 Zustand 更精细更新控制的场景。2. 环境准备与项目初始化接下来我们将通过一个实战项目——“任务看板”Task Board来学习 Amper。这个应用包含任务列表、过滤、增删改查以及异步加载模拟。2.1 技术栈与版本说明运行时Node.js 18 或 Bun 1.0包管理器npm, yarn, pnpm 或 bun 均可本文使用pnpm。前端框架React 18 (使用 Vite 作为构建工具)状态管理amperjs/core与amperjs/reactUI 库使用原生 CSS 模块可选 Tailwind CSS本文为保持焦点使用简单样式。类型检查TypeScript 52.2 创建项目并安装依赖首先使用 Vite 快速创建一个 React TypeScript 项目。# 使用 pnpm pnpm create vite task-board --template react-ts cd task-board # 安装 Amper 核心库及 React 绑定 pnpm add amperjs/core amperjs/react # 安装开发依赖类型声明已包含无需额外安装 pnpm add -D types/node2.3 项目结构预览创建以下目录结构这有助于我们组织代码src/ ├── stores/ # 状态存储 │ ├── taskStore.ts │ └── filterStore.ts ├── components/ # 展示组件 │ ├── TaskList.tsx │ ├── TaskItem.tsx │ ├── AddTaskForm.tsx │ └── FilterBar.tsx ├── types/ # 类型定义 │ └── task.ts ├── utils/ # 工具函数 │ └── api.ts # 模拟 API ├── App.tsx ├── main.tsx └── index.css3. Amper 核心概念与基础语法在编写代码前必须掌握 Amper 的几个核心原语signal,computed,effect以及 React 集成中的useSignal,useComputed。3.1 创建响应式状态signalsignal是 Amper 中最基本的状态单元。你可以把它想象成一个具有超能力的变量当它的值改变时所有依赖它的计算和副作用都会自动更新。// 示例stores/counterStore.ts import { signal } from amperjs/core; // 创建一个 signal并指定其类型为 number初始值为 0 const count signal(0); // 读取值 console.log(count.value); // 输出: 0 // 设置新值 count.value 1; console.log(count.value); // 输出: 1 // 基于当前值更新 count.value 1; console.log(count.value); // 输出: 2signal返回的对象有一个.value属性对其进行读写即触发响应式系统。3.2 创建派生状态computedcomputed用于创建依赖于其他signal或computed的派生值。它也是响应式的并且会缓存计算结果只有在其依赖项变化时才重新计算。// 续上例 import { signal, computed } from amperjs/core; const count signal(0); const doubleCount computed(() count.value * 2); const isEven computed(() count.value % 2 0); console.log(doubleCount.value); // 输出: 0 console.log(isEven.value); // 输出: true count.value 4; console.log(doubleCount.value); // 自动更新为: 8 console.log(isEven.value); // 自动更新为: true3.3 执行副作用effecteffect用于执行有副作用的操作如日志记录、DOM 操作或发起网络请求。它会在创建时立即运行一次并在其依赖的响应式状态变化时重新运行。import { signal, effect } from amperjs/core; const count signal(0); // 每当 count 变化就打印日志 const dispose effect(() { console.log(当前计数是${count.value}); }); // 立即输出: 当前计数是0 count.value 5; // 输出: 当前计数是5 // 当不再需要这个 effect 时可以调用返回的函数来清理它 dispose(); count.value 10; // 不再有日志输出3.4 在 React 中使用useSignal,useComputed,useEffect为了在 React 组件中无缝使用 Amper我们需要amperjs/react提供的钩子。它们将 Amper 的响应式状态“连接”到 React 的组件生命周期。// 示例components/Counter.tsx import { useSignal, useComputed } from amperjs/react; function Counter() { // 在组件内创建响应式状态useSignal 返回的就是一个 signal const count useSignal(0); // 在组件内创建派生状态 const doubleCount useComputed(() count.value * 2); const increment () { count.value 1; }; return ( div p计数: {count.value}/p p双倍计数: {doubleCount.value}/p button onClick{increment}1/button /div ); }关键点在组件中使用useSignal创建的signal其.value的变化会自动触发该组件的重新渲染并且是细粒度的。如果另一个组件只读取doubleCount.value那么当count.value变化时只有依赖count和doubleCount的组件会更新。4. 实战构建任务看板应用现在我们将运用上述概念构建完整的应用。4.1 定义数据类型与模拟 API首先定义任务的数据结构。// src/types/task.ts export type TaskStatus todo | in-progress | done; export type TaskPriority low | medium | high; export interface Task { id: string; title: string; description: string; status: TaskStatus; priority: TaskPriority; createdAt: Date; updatedAt: Date; } export type FilterType all | TaskStatus;然后创建一个模拟的 API 工具函数用于模拟网络请求。// src/utils/api.ts import { Task } from ../types/task; // 模拟延迟 const delay (ms: number) new Promise(resolve setTimeout(resolve, ms)); // 模拟初始数据 let mockTasks: Task[] [ { id: 1, title: 学习 Amper, description: 阅读官方文档并实践, status: done, priority: high, createdAt: new Date(2024-01-01), updatedAt: new Date(2024-01-02) }, { id: 2, title: 编写示例项目, description: 构建一个任务看板应用, status: in-progress, priority: high, createdAt: new Date(2024-01-03), updatedAt: new Date(2024-01-03) }, { id: 3, title: 写技术博客, description: 总结 Amper 使用心得, status: todo, priority: medium, createdAt: new Date(2024-01-04), updatedAt: new Date(2024-01-04) }, ]; export const taskApi { async fetchTasks(): PromiseTask[] { await delay(300); // 模拟网络延迟 return [...mockTasks]; }, async addTask(newTask: OmitTask, id | createdAt | updatedAt): PromiseTask { await delay(300); const task: Task { ...newTask, id: Math.random().toString(36).substring(2, 9), createdAt: new Date(), updatedAt: new Date(), }; mockTasks.push(task); return task; }, async updateTask(id: string, updates: PartialOmitTask, id): PromiseTask | null { await delay(300); const index mockTasks.findIndex(t t.id id); if (index -1) return null; mockTasks[index] { ...mockTasks[index], ...updates, updatedAt: new Date(), }; return mockTasks[index]; }, async deleteTask(id: string): Promiseboolean { await delay(300); const initialLength mockTasks.length; mockTasks mockTasks.filter(t t.id ! id); return mockTasks.length initialLength; }, };4.2 创建状态存储Store这是 Amper 应用的核心。我们将状态和修改状态的逻辑集中在一起。// src/stores/taskStore.ts import { signal, computed } from amperjs/core; import { taskApi } from ../utils/api; import type { Task, TaskStatus } from ../types/task; // 1. 定义状态 const tasks signalTask[]([]); const isLoading signal(false); const error signalstring | null(null); // 2. 定义派生状态计算属性 const todoTasks computed(() tasks.value.filter(t t.status todo)); const inProgressTasks computed(() tasks.value.filter(t t.status in-progress)); const doneTasks computed(() tasks.value.filter(t t.status done)); // 可以根据优先级等进一步计算 const highPriorityTasks computed(() tasks.value.filter(t t.priority high)); // 3. 定义 Actions (修改状态的方法) export const taskStore { // 状态信号本身通常是私有的通过 getter 暴露只读访问 get tasks() { return tasks.value; }, get isLoading() { return isLoading.value; }, get error() { return error.value; }, // 暴露计算信号 get todoTasks() { return todoTasks.value; }, get inProgressTasks() { return inProgressTasks.value; }, get doneTasks() { return doneTasks.value; }, get highPriorityTasks() { return highPriorityTasks.value; }, // 异步 Action加载任务 async loadTasks() { isLoading.value true; error.value null; try { const data await taskApi.fetchTasks(); tasks.value data; // 直接赋值触发所有相关 computed 更新 } catch (err) { error.value err instanceof Error ? err.message : 加载任务失败; } finally { isLoading.value false; } }, // 异步 Action添加任务 async addTask(title: string, description: string, priority: Task[priority]) { isLoading.value true; try { const newTask await taskApi.addTask({ title, description, status: todo, priority, }); // 不可变更新创建新数组 tasks.value [...tasks.value, newTask]; } catch (err) { error.value 添加任务失败; throw err; // 可以向上抛出供 UI 处理 } finally { isLoading.value false; } }, // 同步 Action更新任务状态本地乐观更新 updateTaskStatus(id: string, status: TaskStatus) { const index tasks.value.findIndex(t t.id id); if (index ! -1) { // 创建新数组和新的任务对象遵循不可变原则 const newTasks [...tasks.value]; newTasks[index] { ...newTasks[index], status, updatedAt: new Date() }; tasks.value newTasks; // 可以在这里触发一个异步的 API 调用以持久化 taskApi.updateTask(id, { status }).catch(console.error); } }, // 同步 Action删除任务 deleteTask(id: string) { tasks.value tasks.value.filter(t t.id ! id); taskApi.deleteTask(id).catch(console.error); }, };关键设计我们将signal定义为模块内的私有变量通过一个taskStore对象统一导出只读的getter和可执行的action方法。这种模式类似于“容器”提供了清晰的 API 边界。4.3 创建过滤状态存储过滤逻辑相对独立我们将其放在单独的 store 中。// src/stores/filterStore.ts import { signal, computed } from amperjs/core; import type { FilterType } from ../types/task; import { taskStore } from ./taskStore; // 导入另一个 store // 过滤条件 const currentFilter signalFilterType(all); const searchKeyword signal(); // 派生状态根据过滤条件计算最终要显示的任务列表 // 注意这里 computed 依赖了另一个 store 里的 tasks signal const filteredTasks computed(() { const tasks taskStore.tasks; // 读取只读值 const filter currentFilter.value; const keyword searchKeyword.value.toLowerCase(); let filtered tasks; if (filter ! all) { filtered filtered.filter(t t.status filter); } if (keyword) { filtered filtered.filter(t t.title.toLowerCase().includes(keyword) || t.description.toLowerCase().includes(keyword) ); } return filtered; }); export const filterStore { get currentFilter() { return currentFilter.value; }, get searchKeyword() { return searchKeyword.value; }, get filteredTasks() { return filteredTasks.value; }, setFilter(filter: FilterType) { currentFilter.value filter; }, setSearchKeyword(keyword: string) { searchKeyword.value keyword; }, };4.4 构建 React 组件现在我们将 store 连接到 UI。组件TaskItem.tsx- 展示单个任务// src/components/TaskItem.tsx import React from react; import type { Task } from ../types/task; import { taskStore } from ../stores/taskStore; interface TaskItemProps { task: Task; } const TaskItem: React.FCTaskItemProps ({ task }) { const handleStatusChange (e: React.ChangeEventHTMLSelectElement) { taskStore.updateTaskStatus(task.id, e.target.value as Task[status]); }; const handleDelete () { if (window.confirm(确定删除任务 ${task.title} 吗)) { taskStore.deleteTask(task.id); } }; return ( div classNametask-item style{{ border: 1px solid #ccc, margin: 10px 0, padding: 10px, borderRadius: 5px }} div style{{ display: flex, justifyContent: space-between }} h4 style{{ margin: 0 }}{task.title}/h4 span style{{ backgroundColor: task.priority high ? #ffcccc : task.priority medium ? #fff3cd : #d4edda, padding: 2px 8px, borderRadius: 10px, fontSize: 0.8em }} {task.priority} /span /div p style{{ fontSize: 0.9em, color: #666 }}{task.description}/p div style{{ display: flex, justifyContent: space-between, alignItems: center }} select value{task.status} onChange{handleStatusChange} option valuetodo待办/option option valuein-progress进行中/option option valuedone已完成/option /select button onClick{handleDelete} style{{ background: #dc3545, color: white, border: none, padding: 5px 10px, borderRadius: 3px, cursor: pointer }} 删除 /button /div small style{{ color: #999 }}更新于: {task.updatedAt.toLocaleDateString()}/small /div ); }; export default TaskItem;组件TaskList.tsx- 展示任务列表// src/components/TaskList.tsx import React from react; import { useSignal, useComputed } from amperjs/react; import TaskItem from ./TaskItem; import { filterStore } from ../stores/filterStore; import { taskStore } from ../stores/taskStore; const TaskList: React.FC () { // 使用 useComputed 将 store 中的派生状态转换为响应式的组件状态 const filteredTasks useComputed(() filterStore.filteredTasks); const isLoading useComputed(() taskStore.isLoading); const error useComputed(() taskStore.error); if (isLoading.value) { return div加载中.../div; } if (error.value) { return div style{{ color: red }}错误: {error.value}/div; } if (filteredTasks.value.length 0) { return div暂无任务/div; } return ( div {filteredTasks.value.map(task ( TaskItem key{task.id} task{task} / ))} /div ); }; export default TaskList;注意在组件中我们通过useComputed(() store.getter)来订阅 store 中的状态。当filterStore.filteredTasks依赖的底层signal变化时这个useComputed会返回新的值从而触发组件重新渲染。这是连接 Amper store 和 React 组件的标准模式。组件FilterBar.tsx 和 AddTaskForm.tsx代码略原理相同通过调用filterStore.setFilter和taskStore.addTask来修改状态。4.5 整合主应用最后在App.tsx中组合所有组件并在应用启动时加载数据。// src/App.tsx import React, { useEffect } from react; import { useSignal } from amperjs/react; import TaskList from ./components/TaskList; import AddTaskForm from ./components/AddTaskForm; import FilterBar from ./components/FilterBar; import { taskStore } from ./stores/taskStore; import ./App.css; function App() { // 使用一个本地 signal 触发初始加载 const hasLoaded useSignal(false); useEffect(() { if (!hasLoaded.value) { taskStore.loadTasks(); hasLoaded.value true; } }, [hasLoaded]); return ( div classNameApp style{{ maxWidth: 800px, margin: 0 auto, padding: 20px }} h1任务看板 (Powered by Amper)/h1 AddTaskForm / hr / FilterBar / TaskList / div style{{ marginTop: 20px, fontSize: 0.9em, color: #666 }} p状态统计/p ul li总计: {taskStore.tasks.length}/li li待办: {taskStore.todoTasks.length}/li li进行中: {taskStore.inProgressTasks.length}/li li已完成: {taskStore.doneTasks.length}/li li高优先级: {taskStore.highPriorityTasks.length}/li /ul /div /div ); } export default App;5. 运行与验证在项目根目录运行pnpm devVite 会启动开发服务器。打开浏览器访问http://localhost:5173你将看到一个功能完整的任务看板。你可以尝试以下操作来验证 Amper 的响应式特性添加任务表单提交后任务列表和底部的统计数字会立即更新。过滤任务点击状态筛选或输入关键词列表会实时过滤。更改任务状态下拉选择框改变任务状态该任务会移动到相应的视觉区域通过过滤逻辑同时“更新于”时间会变。打开浏览器开发者工具在组件更新时观察控制台你会发现只有TaskList和显示统计数字的部分会重新渲染而App组件的其他部分不会。这证明了细粒度渲染的效果。6. 常见问题与排查思路在实际使用 Amper 时你可能会遇到以下典型问题问题现象可能原因排查与解决思路状态更新了但组件不重新渲染1. 组件没有通过useSignal或useComputed订阅 signal。2. 直接修改了 signal 内部对象的属性而没有替换整个对象。1. 确保在组件内使用useComputed(() store.someValue)或useSignal来创建/连接状态。2. 对于对象或数组始终采用不可变更新mySignal.value { ...mySignal.value, prop: newValue }或mySignal.value [...mySignal.value, newItem]。computed值没有按预期更新1.computed函数内部没有读取依赖 signal 的.value属性。2. 依赖的 signal 本身没有被正确更新。1. 检查computed函数确保所有依赖都通过.value访问。2. 使用effect监听依赖的 signal打印日志确认其是否变化。在异步操作中更新状态报错在 React 组件卸载后尝试设置 signal 的值。使用useEffect的清理函数或在异步操作前检查组件是否仍挂载。也可以将清理逻辑放在 store 的 action 中。TypeScript 类型推断不准确创建signal时未提供明确的泛型类型。显式声明 signal 的类型const list signalstring[]([])。多个组件共享状态但更新不同步每个组件都用useSignal创建了自己的独立状态实例。确保状态定义在模块作用域或 Context 中。最佳实践是使用我们示例中的“store 模式”将状态定义在模块内组件通过导入同一个 store 实例来共享状态。7. 最佳实践与工程建议将 Amper 用于生产级项目时遵循以下建议可以提升代码质量和维护性7.1 状态组织Store 模式按领域划分 Store如userStore,productStore,uiStore。避免一个巨大的全局 store。私有化 Signal将signal定义在模块内部仅通过getter和action暴露。这强制了单向数据流并使得状态变更可追溯。逻辑复用将复杂的派生状态或通用的更新逻辑封装成 store 内的函数或独立的工具函数。7.2 性能优化善用computed将昂贵的计算包装在computed中利用其缓存机制。只有当依赖项变化时才会重新计算。避免在渲染函数中创建新的computed在 React 组件中将useComputed放在组件顶层而不是渲染逻辑或循环内部。列表渲染对于长列表在TaskList这样的父组件中通过useComputed获取列表然后使用React.memo包裹子组件TaskItem并传递稳定的回调函数可使用useCallback或将回调定义在 store 中。7.3 异步处理统一 Loading 和 Error 状态像示例中一样在 store 中定义isLoading和errorsignal由 actions 统一管理。组件只需订阅它们。乐观更新对于创建、更新、删除操作可以先立即更新本地状态乐观更新再发起异步请求。如果请求失败需要提供回滚机制并提示用户。示例中的updateTaskStatus采用了简单的乐观更新。7.4 与 React 生态集成路由状态可以将当前路由信息存入一个 store供全应用订阅。表单处理对于复杂表单可以为每个字段创建一个signal并使用computed进行表单整体校验。持久化可以使用effect监听特定 signal 的变化并将其同步到localStorage或 IndexedDB。也可以使用amperjs/persist这类社区插件。7.5 测试Store 测试因为 store 是纯 JavaScript 模块不依赖 React可以非常方便地进行单元测试。直接导入 store调用 actions断言 signal 的值。组件测试使用testing-library/react测试组件时需要将 store 提供到组件树中。可以为测试创建特定的 store 实例或使用 Provider 模式。通过这个从概念到实战的完整流程你应该对 Amper 有了深入的理解。它通过极简的原子化响应式原语提供了强大的状态管理能力尤其适合追求高性能和良好开发体验的中大型项目。建议你克隆示例代码亲手运行和修改体会其数据流的变化。下一步可以探索 Amper 的调试工具、持久化插件以及如何在 SSR如 Next.js场景下使用它。 Amper状态管理实战：从响应式原子到任务看板应用开发
最近在技术社区看到不少关于 Amper 的讨论尤其是 Joffrey Bion 分享的《The State of Amper》一文引发了很多开发者对现代前端状态管理方案的重新思考。在 React、Vue 等框架生态日益复杂的今天如何选择一个既轻量又强大、既能应对简单场景又能支撑复杂应用的状态管理库成为了一个高频痛点。本文将深入解析 Amper 的设计理念、核心特性并通过一个完整的实战项目带你从零搭建一个使用 Amper 进行状态管理的现代前端应用。无论你是正在为下一个项目选型纠结的团队负责人还是希望提升技术视野的进阶开发者这篇文章都将提供一套可落地的参考方案。1. Amper 是什么重新理解状态管理在深入代码之前我们有必要厘清 Amper 究竟解决了什么问题以及它与其他流行方案如 Redux, Zustand, Valtio, Jotai的核心差异。1.1 状态管理的核心挑战现代前端应用的状态管理远不止是“存储一个变量”那么简单。它需要处理数据流清晰性状态如何变化变化如何触发 UI 更新这个流程必须可预测、易追踪。组件通信深层嵌套组件间如何高效共享状态避免“prop drilling”。派生状态如何从基础状态计算衍生数据并保持高效更新。副作用管理异步操作如 API 调用如何与状态变更安全、有序地结合。开发者体验代码是否简洁类型提示是否完善调试工具是否强大。1.2 Amper 的设计哲学Amper 由 Joffrey Bion 创建其核心理念是“响应式 原子化”。它并非一个庞大的框架而是一组用于创建响应式数据单元称为“信号”或“原子”和派生状态的原语。它的特点包括极简 API核心概念很少学习曲线平缓。细粒度响应只有真正依赖某个状态的组件才会在该状态变化时重新渲染性能开销极小。不可变与可变性的平衡鼓励不可变更新以保持可预测性但在底层使用可变引用以实现高效更新。框架无关性核心逻辑不依赖任何 UI 框架通过适配器可与 React、Vue、Solid 等集成。出色的 TypeScript 支持提供完整的类型推断开发体验流畅。1.3 与其他方案的对比为了更直观地理解 Amper 的定位我们将其与几个主流方案进行简要对比特性AmperRedux ToolkitZustandValtioJotai心智模型响应式原子单向数据流可变 Store可变代理原子化样板代码极少中等少极少少渲染优化自动细粒度需useSelector优化需手动选择状态自动细粒度自动细粒度异步处理原生支持通过createAsyncThunk在 action 中处理在 action 中处理在 atom 中处理调试工具社区提供官方强大官方提供官方提供官方提供适用场景中到大型应用追求极致性能大型应用需要严格流程中小型应用快速开发中小型应用偏好可变语法原子化需求强的应用Amper 在“简洁性”和“性能”之间找到了一个很好的平衡点特别适合那些觉得 Redux 太重但又需要比 Zustand 更精细更新控制的场景。2. 环境准备与项目初始化接下来我们将通过一个实战项目——“任务看板”Task Board来学习 Amper。这个应用包含任务列表、过滤、增删改查以及异步加载模拟。2.1 技术栈与版本说明运行时Node.js 18 或 Bun 1.0包管理器npm, yarn, pnpm 或 bun 均可本文使用pnpm。前端框架React 18 (使用 Vite 作为构建工具)状态管理amperjs/core与amperjs/reactUI 库使用原生 CSS 模块可选 Tailwind CSS本文为保持焦点使用简单样式。类型检查TypeScript 52.2 创建项目并安装依赖首先使用 Vite 快速创建一个 React TypeScript 项目。# 使用 pnpm pnpm create vite task-board --template react-ts cd task-board # 安装 Amper 核心库及 React 绑定 pnpm add amperjs/core amperjs/react # 安装开发依赖类型声明已包含无需额外安装 pnpm add -D types/node2.3 项目结构预览创建以下目录结构这有助于我们组织代码src/ ├── stores/ # 状态存储 │ ├── taskStore.ts │ └── filterStore.ts ├── components/ # 展示组件 │ ├── TaskList.tsx │ ├── TaskItem.tsx │ ├── AddTaskForm.tsx │ └── FilterBar.tsx ├── types/ # 类型定义 │ └── task.ts ├── utils/ # 工具函数 │ └── api.ts # 模拟 API ├── App.tsx ├── main.tsx └── index.css3. Amper 核心概念与基础语法在编写代码前必须掌握 Amper 的几个核心原语signal,computed,effect以及 React 集成中的useSignal,useComputed。3.1 创建响应式状态signalsignal是 Amper 中最基本的状态单元。你可以把它想象成一个具有超能力的变量当它的值改变时所有依赖它的计算和副作用都会自动更新。// 示例stores/counterStore.ts import { signal } from amperjs/core; // 创建一个 signal并指定其类型为 number初始值为 0 const count signal(0); // 读取值 console.log(count.value); // 输出: 0 // 设置新值 count.value 1; console.log(count.value); // 输出: 1 // 基于当前值更新 count.value 1; console.log(count.value); // 输出: 2signal返回的对象有一个.value属性对其进行读写即触发响应式系统。3.2 创建派生状态computedcomputed用于创建依赖于其他signal或computed的派生值。它也是响应式的并且会缓存计算结果只有在其依赖项变化时才重新计算。// 续上例 import { signal, computed } from amperjs/core; const count signal(0); const doubleCount computed(() count.value * 2); const isEven computed(() count.value % 2 0); console.log(doubleCount.value); // 输出: 0 console.log(isEven.value); // 输出: true count.value 4; console.log(doubleCount.value); // 自动更新为: 8 console.log(isEven.value); // 自动更新为: true3.3 执行副作用effecteffect用于执行有副作用的操作如日志记录、DOM 操作或发起网络请求。它会在创建时立即运行一次并在其依赖的响应式状态变化时重新运行。import { signal, effect } from amperjs/core; const count signal(0); // 每当 count 变化就打印日志 const dispose effect(() { console.log(当前计数是${count.value}); }); // 立即输出: 当前计数是0 count.value 5; // 输出: 当前计数是5 // 当不再需要这个 effect 时可以调用返回的函数来清理它 dispose(); count.value 10; // 不再有日志输出3.4 在 React 中使用useSignal,useComputed,useEffect为了在 React 组件中无缝使用 Amper我们需要amperjs/react提供的钩子。它们将 Amper 的响应式状态“连接”到 React 的组件生命周期。// 示例components/Counter.tsx import { useSignal, useComputed } from amperjs/react; function Counter() { // 在组件内创建响应式状态useSignal 返回的就是一个 signal const count useSignal(0); // 在组件内创建派生状态 const doubleCount useComputed(() count.value * 2); const increment () { count.value 1; }; return ( div p计数: {count.value}/p p双倍计数: {doubleCount.value}/p button onClick{increment}1/button /div ); }关键点在组件中使用useSignal创建的signal其.value的变化会自动触发该组件的重新渲染并且是细粒度的。如果另一个组件只读取doubleCount.value那么当count.value变化时只有依赖count和doubleCount的组件会更新。4. 实战构建任务看板应用现在我们将运用上述概念构建完整的应用。4.1 定义数据类型与模拟 API首先定义任务的数据结构。// src/types/task.ts export type TaskStatus todo | in-progress | done; export type TaskPriority low | medium | high; export interface Task { id: string; title: string; description: string; status: TaskStatus; priority: TaskPriority; createdAt: Date; updatedAt: Date; } export type FilterType all | TaskStatus;然后创建一个模拟的 API 工具函数用于模拟网络请求。// src/utils/api.ts import { Task } from ../types/task; // 模拟延迟 const delay (ms: number) new Promise(resolve setTimeout(resolve, ms)); // 模拟初始数据 let mockTasks: Task[] [ { id: 1, title: 学习 Amper, description: 阅读官方文档并实践, status: done, priority: high, createdAt: new Date(2024-01-01), updatedAt: new Date(2024-01-02) }, { id: 2, title: 编写示例项目, description: 构建一个任务看板应用, status: in-progress, priority: high, createdAt: new Date(2024-01-03), updatedAt: new Date(2024-01-03) }, { id: 3, title: 写技术博客, description: 总结 Amper 使用心得, status: todo, priority: medium, createdAt: new Date(2024-01-04), updatedAt: new Date(2024-01-04) }, ]; export const taskApi { async fetchTasks(): PromiseTask[] { await delay(300); // 模拟网络延迟 return [...mockTasks]; }, async addTask(newTask: OmitTask, id | createdAt | updatedAt): PromiseTask { await delay(300); const task: Task { ...newTask, id: Math.random().toString(36).substring(2, 9), createdAt: new Date(), updatedAt: new Date(), }; mockTasks.push(task); return task; }, async updateTask(id: string, updates: PartialOmitTask, id): PromiseTask | null { await delay(300); const index mockTasks.findIndex(t t.id id); if (index -1) return null; mockTasks[index] { ...mockTasks[index], ...updates, updatedAt: new Date(), }; return mockTasks[index]; }, async deleteTask(id: string): Promiseboolean { await delay(300); const initialLength mockTasks.length; mockTasks mockTasks.filter(t t.id ! id); return mockTasks.length initialLength; }, };4.2 创建状态存储Store这是 Amper 应用的核心。我们将状态和修改状态的逻辑集中在一起。// src/stores/taskStore.ts import { signal, computed } from amperjs/core; import { taskApi } from ../utils/api; import type { Task, TaskStatus } from ../types/task; // 1. 定义状态 const tasks signalTask[]([]); const isLoading signal(false); const error signalstring | null(null); // 2. 定义派生状态计算属性 const todoTasks computed(() tasks.value.filter(t t.status todo)); const inProgressTasks computed(() tasks.value.filter(t t.status in-progress)); const doneTasks computed(() tasks.value.filter(t t.status done)); // 可以根据优先级等进一步计算 const highPriorityTasks computed(() tasks.value.filter(t t.priority high)); // 3. 定义 Actions (修改状态的方法) export const taskStore { // 状态信号本身通常是私有的通过 getter 暴露只读访问 get tasks() { return tasks.value; }, get isLoading() { return isLoading.value; }, get error() { return error.value; }, // 暴露计算信号 get todoTasks() { return todoTasks.value; }, get inProgressTasks() { return inProgressTasks.value; }, get doneTasks() { return doneTasks.value; }, get highPriorityTasks() { return highPriorityTasks.value; }, // 异步 Action加载任务 async loadTasks() { isLoading.value true; error.value null; try { const data await taskApi.fetchTasks(); tasks.value data; // 直接赋值触发所有相关 computed 更新 } catch (err) { error.value err instanceof Error ? err.message : 加载任务失败; } finally { isLoading.value false; } }, // 异步 Action添加任务 async addTask(title: string, description: string, priority: Task[priority]) { isLoading.value true; try { const newTask await taskApi.addTask({ title, description, status: todo, priority, }); // 不可变更新创建新数组 tasks.value [...tasks.value, newTask]; } catch (err) { error.value 添加任务失败; throw err; // 可以向上抛出供 UI 处理 } finally { isLoading.value false; } }, // 同步 Action更新任务状态本地乐观更新 updateTaskStatus(id: string, status: TaskStatus) { const index tasks.value.findIndex(t t.id id); if (index ! -1) { // 创建新数组和新的任务对象遵循不可变原则 const newTasks [...tasks.value]; newTasks[index] { ...newTasks[index], status, updatedAt: new Date() }; tasks.value newTasks; // 可以在这里触发一个异步的 API 调用以持久化 taskApi.updateTask(id, { status }).catch(console.error); } }, // 同步 Action删除任务 deleteTask(id: string) { tasks.value tasks.value.filter(t t.id ! id); taskApi.deleteTask(id).catch(console.error); }, };关键设计我们将signal定义为模块内的私有变量通过一个taskStore对象统一导出只读的getter和可执行的action方法。这种模式类似于“容器”提供了清晰的 API 边界。4.3 创建过滤状态存储过滤逻辑相对独立我们将其放在单独的 store 中。// src/stores/filterStore.ts import { signal, computed } from amperjs/core; import type { FilterType } from ../types/task; import { taskStore } from ./taskStore; // 导入另一个 store // 过滤条件 const currentFilter signalFilterType(all); const searchKeyword signal(); // 派生状态根据过滤条件计算最终要显示的任务列表 // 注意这里 computed 依赖了另一个 store 里的 tasks signal const filteredTasks computed(() { const tasks taskStore.tasks; // 读取只读值 const filter currentFilter.value; const keyword searchKeyword.value.toLowerCase(); let filtered tasks; if (filter ! all) { filtered filtered.filter(t t.status filter); } if (keyword) { filtered filtered.filter(t t.title.toLowerCase().includes(keyword) || t.description.toLowerCase().includes(keyword) ); } return filtered; }); export const filterStore { get currentFilter() { return currentFilter.value; }, get searchKeyword() { return searchKeyword.value; }, get filteredTasks() { return filteredTasks.value; }, setFilter(filter: FilterType) { currentFilter.value filter; }, setSearchKeyword(keyword: string) { searchKeyword.value keyword; }, };4.4 构建 React 组件现在我们将 store 连接到 UI。组件TaskItem.tsx- 展示单个任务// src/components/TaskItem.tsx import React from react; import type { Task } from ../types/task; import { taskStore } from ../stores/taskStore; interface TaskItemProps { task: Task; } const TaskItem: React.FCTaskItemProps ({ task }) { const handleStatusChange (e: React.ChangeEventHTMLSelectElement) { taskStore.updateTaskStatus(task.id, e.target.value as Task[status]); }; const handleDelete () { if (window.confirm(确定删除任务 ${task.title} 吗)) { taskStore.deleteTask(task.id); } }; return ( div classNametask-item style{{ border: 1px solid #ccc, margin: 10px 0, padding: 10px, borderRadius: 5px }} div style{{ display: flex, justifyContent: space-between }} h4 style{{ margin: 0 }}{task.title}/h4 span style{{ backgroundColor: task.priority high ? #ffcccc : task.priority medium ? #fff3cd : #d4edda, padding: 2px 8px, borderRadius: 10px, fontSize: 0.8em }} {task.priority} /span /div p style{{ fontSize: 0.9em, color: #666 }}{task.description}/p div style{{ display: flex, justifyContent: space-between, alignItems: center }} select value{task.status} onChange{handleStatusChange} option valuetodo待办/option option valuein-progress进行中/option option valuedone已完成/option /select button onClick{handleDelete} style{{ background: #dc3545, color: white, border: none, padding: 5px 10px, borderRadius: 3px, cursor: pointer }} 删除 /button /div small style{{ color: #999 }}更新于: {task.updatedAt.toLocaleDateString()}/small /div ); }; export default TaskItem;组件TaskList.tsx- 展示任务列表// src/components/TaskList.tsx import React from react; import { useSignal, useComputed } from amperjs/react; import TaskItem from ./TaskItem; import { filterStore } from ../stores/filterStore; import { taskStore } from ../stores/taskStore; const TaskList: React.FC () { // 使用 useComputed 将 store 中的派生状态转换为响应式的组件状态 const filteredTasks useComputed(() filterStore.filteredTasks); const isLoading useComputed(() taskStore.isLoading); const error useComputed(() taskStore.error); if (isLoading.value) { return div加载中.../div; } if (error.value) { return div style{{ color: red }}错误: {error.value}/div; } if (filteredTasks.value.length 0) { return div暂无任务/div; } return ( div {filteredTasks.value.map(task ( TaskItem key{task.id} task{task} / ))} /div ); }; export default TaskList;注意在组件中我们通过useComputed(() store.getter)来订阅 store 中的状态。当filterStore.filteredTasks依赖的底层signal变化时这个useComputed会返回新的值从而触发组件重新渲染。这是连接 Amper store 和 React 组件的标准模式。组件FilterBar.tsx 和 AddTaskForm.tsx代码略原理相同通过调用filterStore.setFilter和taskStore.addTask来修改状态。4.5 整合主应用最后在App.tsx中组合所有组件并在应用启动时加载数据。// src/App.tsx import React, { useEffect } from react; import { useSignal } from amperjs/react; import TaskList from ./components/TaskList; import AddTaskForm from ./components/AddTaskForm; import FilterBar from ./components/FilterBar; import { taskStore } from ./stores/taskStore; import ./App.css; function App() { // 使用一个本地 signal 触发初始加载 const hasLoaded useSignal(false); useEffect(() { if (!hasLoaded.value) { taskStore.loadTasks(); hasLoaded.value true; } }, [hasLoaded]); return ( div classNameApp style{{ maxWidth: 800px, margin: 0 auto, padding: 20px }} h1任务看板 (Powered by Amper)/h1 AddTaskForm / hr / FilterBar / TaskList / div style{{ marginTop: 20px, fontSize: 0.9em, color: #666 }} p状态统计/p ul li总计: {taskStore.tasks.length}/li li待办: {taskStore.todoTasks.length}/li li进行中: {taskStore.inProgressTasks.length}/li li已完成: {taskStore.doneTasks.length}/li li高优先级: {taskStore.highPriorityTasks.length}/li /ul /div /div ); } export default App;5. 运行与验证在项目根目录运行pnpm devVite 会启动开发服务器。打开浏览器访问http://localhost:5173你将看到一个功能完整的任务看板。你可以尝试以下操作来验证 Amper 的响应式特性添加任务表单提交后任务列表和底部的统计数字会立即更新。过滤任务点击状态筛选或输入关键词列表会实时过滤。更改任务状态下拉选择框改变任务状态该任务会移动到相应的视觉区域通过过滤逻辑同时“更新于”时间会变。打开浏览器开发者工具在组件更新时观察控制台你会发现只有TaskList和显示统计数字的部分会重新渲染而App组件的其他部分不会。这证明了细粒度渲染的效果。6. 常见问题与排查思路在实际使用 Amper 时你可能会遇到以下典型问题问题现象可能原因排查与解决思路状态更新了但组件不重新渲染1. 组件没有通过useSignal或useComputed订阅 signal。2. 直接修改了 signal 内部对象的属性而没有替换整个对象。1. 确保在组件内使用useComputed(() store.someValue)或useSignal来创建/连接状态。2. 对于对象或数组始终采用不可变更新mySignal.value { ...mySignal.value, prop: newValue }或mySignal.value [...mySignal.value, newItem]。computed值没有按预期更新1.computed函数内部没有读取依赖 signal 的.value属性。2. 依赖的 signal 本身没有被正确更新。1. 检查computed函数确保所有依赖都通过.value访问。2. 使用effect监听依赖的 signal打印日志确认其是否变化。在异步操作中更新状态报错在 React 组件卸载后尝试设置 signal 的值。使用useEffect的清理函数或在异步操作前检查组件是否仍挂载。也可以将清理逻辑放在 store 的 action 中。TypeScript 类型推断不准确创建signal时未提供明确的泛型类型。显式声明 signal 的类型const list signalstring[]([])。多个组件共享状态但更新不同步每个组件都用useSignal创建了自己的独立状态实例。确保状态定义在模块作用域或 Context 中。最佳实践是使用我们示例中的“store 模式”将状态定义在模块内组件通过导入同一个 store 实例来共享状态。7. 最佳实践与工程建议将 Amper 用于生产级项目时遵循以下建议可以提升代码质量和维护性7.1 状态组织Store 模式按领域划分 Store如userStore,productStore,uiStore。避免一个巨大的全局 store。私有化 Signal将signal定义在模块内部仅通过getter和action暴露。这强制了单向数据流并使得状态变更可追溯。逻辑复用将复杂的派生状态或通用的更新逻辑封装成 store 内的函数或独立的工具函数。7.2 性能优化善用computed将昂贵的计算包装在computed中利用其缓存机制。只有当依赖项变化时才会重新计算。避免在渲染函数中创建新的computed在 React 组件中将useComputed放在组件顶层而不是渲染逻辑或循环内部。列表渲染对于长列表在TaskList这样的父组件中通过useComputed获取列表然后使用React.memo包裹子组件TaskItem并传递稳定的回调函数可使用useCallback或将回调定义在 store 中。7.3 异步处理统一 Loading 和 Error 状态像示例中一样在 store 中定义isLoading和errorsignal由 actions 统一管理。组件只需订阅它们。乐观更新对于创建、更新、删除操作可以先立即更新本地状态乐观更新再发起异步请求。如果请求失败需要提供回滚机制并提示用户。示例中的updateTaskStatus采用了简单的乐观更新。7.4 与 React 生态集成路由状态可以将当前路由信息存入一个 store供全应用订阅。表单处理对于复杂表单可以为每个字段创建一个signal并使用computed进行表单整体校验。持久化可以使用effect监听特定 signal 的变化并将其同步到localStorage或 IndexedDB。也可以使用amperjs/persist这类社区插件。7.5 测试Store 测试因为 store 是纯 JavaScript 模块不依赖 React可以非常方便地进行单元测试。直接导入 store调用 actions断言 signal 的值。组件测试使用testing-library/react测试组件时需要将 store 提供到组件树中。可以为测试创建特定的 store 实例或使用 Provider 模式。通过这个从概念到实战的完整流程你应该对 Amper 有了深入的理解。它通过极简的原子化响应式原语提供了强大的状态管理能力尤其适合追求高性能和良好开发体验的中大型项目。建议你克隆示例代码亲手运行和修改体会其数据流的变化。下一步可以探索 Amper 的调试工具、持久化插件以及如何在 SSR如 Next.js场景下使用它。