前端后端【免费下载链接】xstateState machines, statecharts, and actors for complex logic项目地址https://gitcode.com/gh_mirrors/xs/xstate点击查看免费下载本指南以本仓库 packages/xstate-svelte/CHANGELOG.md 为骨架系统梳理xstate/svelte从 0.1.x 到 5.0.0 的关键版本演进涵盖useMachine、useActor、useActorRef、useSelector四个核心 API 的返回值变迁、类型安全强化、Svelte 版本兼容范围与性能优化并结合仓库内 src 目录 的源码实现与 test 目录 的测试用例进行佐证。读完本文你将掌握如何在不同版本约束下正确使用这套 Svelte 绑定理解input类型强约束、快照订阅与选择器机制背后的实现原理。包定位XState 与 Svelte 之间的桥梁xstate/svelte是 XState 官方为 Svelte 提供的绑定包用于在 Svelte 组件中直接消费 XState 状态机State Machine、状态图Statechart与 Actor。本仓库中该包位于 packages/xstate-svelte其 package.json 声明了peerDependenciessvelte: ^3.24.1 || ^4 || ^5即同时支持 Svelte 3.24.1、Svelte 4 与 Svelte 5xstate则作为可选 peer 依赖optional: true且当前包版本为 5.0.0配套依赖xstate5.20.0。该包对外只暴露四个函数见 src/index.tsuseMachine在组件中创建并启动一个状态机 actoruseActor消费任意 actor 逻辑machine、promise、observable、callback 等返回快照与发送函数useActorRef创建并启动 actor返回 actor 引用useSelector从 actor 快照中派生选择值返回一个仅在所选值变化时才更新的 Svelte store。包本身无运行时副作用sideEffects: false并提供了 CJS/ESM 双构建与exports字段约束导入边界。安装与快速上手按照 packages/xstate-svelte/README.md 的 Quick Start安装依赖npm i xstate xstate/svelte随后在 Svelte 组件中使用useMachinescript import { useMachine } from xstate/svelte; import { createMachine } from xstate; const toggleMachine createMachine({ id: toggle, initial: inactive, states: { inactive: { on: { TOGGLE: active } }, active: { on: { TOGGLE: inactive } } } }); const { state, send } useMachine(toggleMachine); /script button on:click{() send(TOGGLE)} {$state.value inactive ? Click to activate : Active! Click to deactivate} /button注意README 中的示例仍使用 v1/v2 时代的{ state, send }解构写法。自3.0.0起详见下文返回值已改为{ snapshot, send, actorRef }新代码应写作const { snapshot, send } useMachine(toggleMachine);两者等价是因为useMachine在源码中只是useActor的别名src/useMachine.ts 中标注/** alias useActor */而useActor的返回值是{ snapshot, send, actorRef }。核心 API 演进主线3.0.0从 state/service 到 snapshot/actorRef返回值重构拥抱 Actor 模型CHANGELOG 中3.0.0记录了最重大的一次破坏性变更PR #4507useMachine(machine)的返回值从{ state, send, service }改为{ snapshot, send, actorRef }const { - state, snapshot, send, - service actorRef } useMachine(machine);这一变化对应 XState v5 的 Actor 化架构service被统一为 actor 引用actorRef状态对象被统称为快照snapshot。快照通过 Svelte 的Readablestore 暴露因此在模板中通过$snapshot读取。在 src/useActor.ts 中可以看到完整实现const actorRef useActorRef(logic, options); let currentSnapshot actorRef.getSnapshot(); const snapshot readable(currentSnapshot, (set) { return actorRef.subscribe((nextSnapshot) { if (currentSnapshot ! nextSnapshot) { currentSnapshot nextSnapshot; set(currentSnapshot); } }).unsubscribe; }); return { snapshot, send: actorRef.send, actorRef };要点snapshot由 Svelte 内置的readable创建初始值为actorRef.getSnapshot()订阅期间只有快照引用变化currentSnapshot ! nextSnapshot时才触发更新避免无意义的重新渲染send直接指向actorRef.sendactorRef本身也会被返回供useSelector或事件发送使用。新增 useActorRef 与 useActor3.0.0同版本PR #4507新增了useActorRef(logic)与useActor(logic)两个 hook。useActorRef的源码src/useActorRef.ts展示了生命周期管理的关键设计const actorRef createActor(logic, options).start(); onDestroy(() actorRef.stop()); return actorRef;即组件挂载时通过createActor(logic, options).start()创建并启动 actor组件销毁onDestroy时调用actorRef.stop()停止 actor。actor 的生命周期与组件生命周期严格绑定。FSM 相关函数移除3.0.0CHANGELOG 同时记录PR #4265FSM 相关函数已被移除。这是 XState v5 全面收敛到统一 actor 模型的一部分——不再区分普通状态机与轻量 FSM两套 API所有逻辑都用createActor/ actor 语义处理。如果你曾使用xstate/fsm相关的绑定函数升级到 3.0.0 后需要迁移到统一的useActor/useActorRef。exports 字段收紧公共 API 边界3.0.03.0.0 的另一个 Minor 变更PR #3727是给 package.json 增加exports字段exports: { .: { types: { import: ./dist/xstate-svelte.cjs.mjs, default: ./dist/xstate-svelte.cjs.js }, module: ./dist/xstate-svelte.esm.js, import: ./dist/xstate-svelte.cjs.mjs, default: ./dist/xstate-svelte.cjs.js }, ./package.json: ./package.json }它限制了可导入的文件范围——不再允许从未被认定为公共 API 的内部文件中导入。这意味着使用者只能import { useMachine } from xstate/svelte而不能深入dist内部路径为后续版本演进留出安全空间。useMachine 标记为 alias 而非 deprecated3.0.13.0.1PR #4591将useMachine标记为useActor的aliased别名而非 deprecated弃用。正如上文源码所示useMachine仅仅转发给useActor保留它只是为了降低迁移成本与语义清晰度。因此你可以在两种写法间自由选择不会收到弃用警告。移除 typegen 缺失实现检测类型3.0.23.0.2PR #4600提到Typegen-based types for detecting missing implementations have been removed internally.。即在内部移除了基于 typegen类型生成器的检测缺失实现的类型逻辑——这属于内部类型基础设施的清理对正常使用useMachine/useActor的公开 API 形态没有影响但意味着依赖 typegen 缺失实现提示的旧工作流需要改用 Svelte 5 的类型检查或人工校验。类型安全强化input 必填约束3.0.43.0.4PR #5055是一项重要的类型安全改进useActor、useMachine、useActorRef的类型现在会在types/input中定义了 input 时强制要求传入input。变更前即使机器人在setup的types.input中声明了输入类型调用useMachine(machine)也不会在编译期报错但运行时可能因缺少 input 而崩溃const machine setup({ types: { input: {} as { value: number } } }).createMachine({}); function App() { // 即便未定义 input编译期也不会报错但存在运行时崩溃风险 const _ useMachine(machine); return /; }变更后上述代码会直接产生类型错误input变为必填const machine setup({ types: { input: {} as { value: number } } }).createMachine({}); function App() { // 现在 input 在编译期即被要求提供 const _ useMachine(machine, { input: { value: 1 } }); return /; }这一约束的实现位于 src/useActorRef.ts、src/useActor.ts 与 src/useMachine.ts 共用的类型体操上...[options]: ConditionalRequired [ options?: ActorOptionsTLogic { [K in RequiredActorOptionsKeysTLogic]: unknown; } ], IsNotNeverRequiredActorOptionsKeysTLogic 即RequiredActorOptionsKeysTLogic非空意味着逻辑的types.input已声明时options由可选项变为必选项从而在编译期就拦截忘记传 input这一常见运行时错误。兼容性扩展Svelte 4 与 Svelte 52.1.0 与 4.0.12.1.0PR #4128peer dependency 范围允许Svelte 44.0.1PR #5131进一步将Svelte 5加入允许的 peer dependency 范围。最终在 package.json 中体现为peerDependencies: { svelte: ^3.24.1 || ^4 || ^5, xstate: workspace:^ }结合当前仓库的devDependenciessvelte: ^5.0.0、sveltejs/vite-plugin-svelte: ^4.0.0可以看到该包已基于 Svelte 5 进行开发与测试。升级到 Svelte 5 时$state等新响应式语法与useMachine返回的Readablestore 可以并存——store 的自动解引用$snapshot在 Svelte 5 中仍然受支持。性能与行为修复useSelector 的演进选择器机制引入0.2.0useSelector(actor, selector)于0.2.0PR #2614加入。它订阅 actor并返回一个 Svelte store该 store 表示由selector(snapshot)派生出的选中值script // 只有当所选值发生变化时该 store 才会更新 const value useSelector(service, (state) state.context.value); /script p{$value}/p这解决了直接订阅整个快照时的过度渲染问题组件只对关心的切片slice产生响应。性能优化避免 get 调用2.0.12.0.1PR #3603Improve performance of theuseSelectorby avoidingget——通过避免调用 Svelte 的get函数来提升性能。在 src/useSelector.ts 的当前实现中可以看到这一思路的延续let prevSelected selector(actor.getSnapshot()); const selected readable(prevSelected, (set) { const onNext (snapshot: SnapshotFromTActor) { const nextSelected selector(snapshot); if (!compare(prevSelected, nextSelected)) { prevSelected nextSelected; set(nextSelected); } }; // 确保 store 在被订阅时拿到最新值 onNext(actor.getSnapshot()); sub actor.subscribe(onNext); return () { sub.unsubscribe(); }; });关键设计默认比较函数是引用相等a bdefaultCompare即选中值引用变化才通知订阅者支持传入自定义compare函数用于自定义相等语义如大小写不敏感比较在订阅建立时立即用当前快照执行一次onNext保证store 创建之后、订阅之前状态已经变化的场景下订阅者拿到的一定是最新选中值——这正是 test/useSelector.test.ts 中should have an updated value when the store is subscribed to after the state changed用例所覆盖的行为停止订阅时调用sub.unsubscribe()无内存泄漏。兼容 xstate/store3.0.33.0.3PR #4844将xstate/react中的useSelector兼容到xstate/store的 store。虽然这条记录原文针对 React 包但结合本包 src/useSelector.ts 的泛型签名——TActor extends PickAnyActorRef, getSnapshot | subscribe——可以看出同样的契约同样适用于 Svelte 包只要对象实现了getSnapshot与subscribe两个方法这正是 actor 与xstate/store的 store 共同满足的接口useSelector就能对其工作。因此你可以在 Svelte 组件中直接用useSelector订阅xstate/store创建的 store。选择器效果的测试验证仓库测试 packages/xstate-svelte/test/useSelector.test.ts 与 UseSelector.svelte 验证了只在选中值变化时更新的核心语义点击INCREMENT按钮后count变化带选择器与不带选择器的计数器都 1点击INCREMENT_ANOTHER按钮后未选中anotherCount的withSelector保持 1而订阅整个快照的withoutSelector变为 2自定义比较函数用例UseSelectorCustomFn.svelte验证大小写不敏感比较下david到DAVID不会触发更新直到值真正变为other才更新。生命周期与订阅行为修复订阅数归零不停机2.0.02.0.0PR #3172修复了一个关键问题useMachine创建的内部解释器interpreter在其订阅者数量降为零时会被取消订阅。正确行为是解释器的生命周期应绑定到创建它的组件生命周期而不是订阅者的数量。当前 src/useActorRef.ts 的实现正体现了该修复——onDestroy(() actorRef.stop())只在组件销毁时停止 actor。对应测试位于 packages/xstate-svelte/test/useActor.test.ts 的should not stop the interpreter even if subscribers count go temporarily to zero用例通过UseActorNonPersistentSubscription组件反复切换订阅/取消订阅场景验证 actor 内部状态count在订阅者暂时为零后依然保持并能继续累加。ESM 构建2.0.02.0.0PR #3209新增 ESM 构建产物用于修复部分打包问题对应 xstate 仓库 issue #2642。这也是 package.json 中module: dist/xstate-svelte.esm.js与exports中module/import条件的来源。现代打包器Vite、Rollup、webpack 5会优先消费 ESM 构建从而获得更好的 tree-shaking 与更少的打包兼容问题。懒加载 context 中 spawn 的修复0.1.10.1.1PR #2522修复了useMachine/useInterpret在懒求值 context中定义 actor 时无法正确 spawn 的问题createMachine({ // lazy context context: () ({ ref: spawn(() {}) }) });这一修复保证了惰性初始化的 context 里 spawn 出的 actor 能随机器正常启动。版本升级路径一览版本类型关键变更对使用者的影响0.1.1Patch修复懒 context 中 spawn无破坏性0.2.0Minor新增useSelector(actor, selector)新 API可选迁移1.0.0Patch依赖更新含xstate/fsm2.0.0无破坏性2.0.0Major集成 typegen要求 TS 4.0泛型参数收敛为单一TMachine修复订阅数归零停机新增 ESM 构建破坏性泛型签名变化需升级 TS2.0.1PatchuseSelector性能优化避免get无破坏性2.1.0Minor允许 Svelte 4无破坏性3.0.0MajoruseMachine返回{ snapshot, send, actorRef }移除 FSM 函数新增useActorRef/useActor新增exports字段破坏性state/service改名3.0.1PatchuseMachine标记为 alias无破坏性3.0.2Patch移除内部 typegen 缺失实现检测类型内部类型清理3.0.3PatchuseSelector兼容xstate/storestore新能力3.0.4Patchinput在类型中声明后变为必填类型检查更严格3.0.5Patch依赖更新xstate5.18.2无破坏性4.0.0Patch依赖更新xstate5.19.0无破坏性4.0.1Patch允许 Svelte 5无破坏性4.0.2–4.0.5Patch依赖更新xstate5.19.1–5.19.4无破坏性5.0.0Patch依赖更新xstate5.20.0无破坏性从源码验证的底层调用链综合 src 目录四个 API 的依赖关系可以归纳为一条清晰链路useMachine ──▶ useActor ──▶ useActorRef ──▶ createActor(logic, options).start() │ └──────── onDestroy(() actorRef.stop()) └──▶ readable actorRef.subscribe → snapshot store useSelector(actorRef, selector, compare) → readable 派生 store组件级入口useMachine/useActor/useActorRefactor 创建统一走createActor来自xstate核心包见 packages/core/src/createActor.ts响应式封装useActor用readable包裹快照订阅useSelector用readable包裹选择器派生清理时机均在 Svelte 的onDestroy或 store 停止回调中取消订阅 / 停止 actor。这种actor 持有 store 投影的设计使得 XState v5 的 Actor 模型可以无缝映射到 Svelte 的响应式 store 体系——这也是理解整个 CHANGELOG 演进从service到actorRef、从state到snapshot的核心线索。实践建议新项目直接使用 5.x 写法统一采用{ snapshot, send, actorRef }解构避免沿袭 README 中旧版{ state, send }示例为机器定义types.input时务必传input3.0.4 起编译期会强制校验这是防运行时崩溃的最有效手段用useSelector收敛渲染粒度优先选择最小切片而非订阅整个快照配合自定义compare实现深层相等语义生命周期交给框架不要手动 stop 由useActorRef创建的 actor组件销毁时onDestroy会自动处理Svelte 3/4/5 兼容xstate/svelte的 peer 范围覆盖^3.24.1 || ^4 || ^5升级 Svelte 大版本无需更换绑定包。如需进一步阅读可查看包内测试 useActor.test.ts 与 useSelector.test.ts它们同时展示了状态机 rehydration通过getPersistedSnapshot恢复快照与 actor 提供者注入machine.provide({ actors })的真实用法。赞分享前端后端【免费下载链接】xstateState machines, statecharts, and actors for complex logic项目地址https://gitcode.com/gh_mirrors/xs/xstate点击查看免费下载相关推荐Upsonic Applied Scientist 实验流水线之 Implement 阶段论文新方法的公平复现、效率采样与结构化日志落盘Upsonic Applied Scientist 实验流水线之 Implement 阶段论文新方法的公平复现、效率采样与结构化日志落盘 本篇技术指南聚焦于前端后端xstate/store-svelte在 Svelte 应用中接入 XState Store 事件驱动状态管理xstate/store svelte在 Svelte 应用中接入 XState Store 事件驱动状态管理 xstate/store svelte 是前端后端BuildKit 靠哪 3 个设计让构建更快更省缓存BuildKit 靠哪 3 个设计让构建更快更省缓存 如果你的 Dockerfile 改一行就让整条流水线从头跑CI 里反复等待依赖下载问题多半不在 Doc前端后端上一篇N_m3u8DL-CLI-SimpleG让M3U8视频下载变得简单直观下一篇AlienFX Tools免费解锁Alienware灯光与风扇控制的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
