xstate

<p align="center"> <br /> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/statelyai/public-assets/main/logos/xstate-logo-white-nobg.svg"> <img alt="XState 标志" src="https://yellow-cdn.veclightyear.com/2b54e442/afa8b93c-1a30-4acb-95f1-15b02a4b6e18.svg" width="200"> </picture> <br /> <strong>基于 Actor 的复杂应用逻辑状态管理与编排。</strong> <a href="https://stately.ai/docs">→ 文档</a> <br /> <br /> </p>

XState 是一个用于 JavaScript 和 TypeScript 应用的状态管理和编排解决方案。它没有任何依赖，适用于前端和后端应用逻辑。

它使用事件驱动编程、状态机、状态图和 Actor 模型以可预测、稳健和可视化的方式处理复杂逻辑。XState 通过允许开发者将逻辑建模为 Actor 和状态机，提供了一种强大而灵活的方式来管理应用程序和工作流状态。

✨ 在 Stately Studio 中可视化创建状态机 → state.new

📖 阅读文档

➡️ 使用 Stately 编辑器创建状态机

🖥 下载我们的 VS Code 扩展

📑 灵感来自 SCXML 规范

💬 在 Stately Discord 社区中聊天

✍️ 浏览众多 XState 示例

模板

通过在 CodeSandbox 上 fork 以下模板之一开始：

🤖 XState 模板 (CodeSandbox)

</td> <td>

XState v5
TypeScript
无框架

</td> </tr> <tr> <td>

⚛️ XState + React 模板 (CodeSandbox)

</td> <td>

React
XState v5
TypeScript

</td> </tr> <tr> <td>

💚 XState + Vue 模板 (CodeSandbox)

</td> <td>

Vue
XState v5
TypeScript

</td> </tr> <tr> <td>

🧡 XState + Svelte 模板 (CodeSandbox)

</td> <td>

Svelte
XState v5
TypeScript

</td> </tr> </tbody> </table>

超快速入门

npm install xstate

import { createMachine, createActor, assign } from 'xstate';

// 状态机
const toggleMachine = createMachine({
  id: 'toggle',
  initial: 'inactive',
  context: {
    count: 0
  },
  states: {
    inactive: {
      on: {
        TOGGLE: { target: 'active' }
      }
    },
    active: {
      entry: assign({ count: ({ context }) => context.count + 1 }),
      on: {
        TOGGLE: { target: 'inactive' }
      }
    }
  }
});

// Actor（机器逻辑的实例，类似于 store）
const toggleActor = createActor(toggleMachine);
toggleActor.subscribe((state) => console.log(state.value, state.context));
toggleActor.start();
// => 输出 'inactive', { count: 0 }

toggleActor.send({ type: 'TOGGLE' });
// => 输出 'active', { count: 1 }

toggleActor.send({ type: 'TOGGLE' });
// => 输出 'inactive', { count: 1 }

Stately Studio

可视化创建、编辑和协作状态机
导出为多种格式，包括 XState v5
自动生成测试路径和文档
部署到 Stately Sky
使用 Stately AI 生成和修改状态机

state.new

为什么使用？

状态图是一种用于建模有状态、响应式系统的形式化方法。这对于以声明式方式描述应用程序的行为非常有用，从单个组件到整体应用逻辑。

阅读 📽 幻灯片（🎥 视频）或查看以下资源，了解有限状态机和状态图在用户界面中的重要性：

David Harel 的 Statecharts - A Visual Formalism for Complex Systems
Erik Mogensen 的 The World of Statecharts

包

包	描述
🤖 `xstate`	核心有限状态机和状态图库 + 解释器
📉 `@xstate/graph`	使用 XState 的图遍历和基于模型的测试工具
⚛️ `@xstate/react`	在 React 应用中使用 XState 的 React hooks 和工具
💚 `@xstate/vue`	在 Vue 应用中使用 XState 的 Vue 组合函数和工具
🎷 `@xstate/svelte`	在 Svelte 应用中使用 XState 的 Svelte 工具
🥏 `@xstate/solid`	在 Solid 应用中使用 XState 的 Solid hooks 和工具
🔍 `@statelyai/inspect`	XState 的检查工具

有限状态机

import { createMachine, createActor } from 'xstate';

const lightMachine = createMachine({
  id: 'light',
  initial: 'green',
  states: {
    green: {
      on: {
        TIMER: 'yellow'
      }
    },
    yellow: {
      on: {
        TIMER: 'red'
      }
    },
    red: {
      on: {
        TIMER: 'green'
      }
    }
  }
});

const actor = createActor(lightMachine);

actor.subscribe((state) => {
  console.log(state.value);
});

actor.start();
// 输出 'green'

actor.send({ type: 'TIMER' });
// 输出 'yellow'

<table> <thead><tr><th>代码</th><th>状态图</th></tr></thead> <tbody> <tr> <td> </td> <td> </td> </tr> </tbody> </table> </td> <td> <a href="https://stately.ai/registry/editor/fa443471-b416-4014-8e6f-12417863e4d4?mode=design&machineId=27e86036-f2f7-40f1-9d1e-66ce6e1accc0" title="有限状态"> <img src="https://github.com/statelyai/xstate/assets/1093738/36d4b6b5-e3d0-4c19-9f41-2e3425ceac88" alt="有限状态" width="400" /> <br /> 在 Stately Studio 中打开 </a> <br /> </td> </tbody> </table>

层次（嵌套）状态机

import { createMachine, createActor } from 'xstate';

const pedestrianStates = {
  initial: 'walk',
  states: {
    walk: {
      on: {
        PED_TIMER: 'wait'
      }
    },
    wait: {
      on: {
        PED_TIMER: 'stop'
      }
    },
    stop: {}
  }
};

const lightMachine = createMachine({
  id: 'light',
  initial: 'green',
  states: {
    green: {
      on: {
        TIMER: 'yellow'
      }
    },
    yellow: {
      on: {
        TIMER: 'red'
      }
    },
    red: {
      on: {
        TIMER: 'green'
      },
      ...pedestrianStates
    }
  }
});

const actor = createActor(lightMachine);

actor.subscribe((state) => {
  console.log(state.value);
});

actor.start();
// 输出 'green'

actor.send({ type: 'TIMER' });
// 输出 'yellow'

actor.send({ type: 'TIMER' });
// 输出 { red: 'walk' }

actor.send({ type: 'PED_TIMER' });
// 输出 { red: 'wait' }

</td> <td> <a href="https://stately.ai/registry/editor/fa443471-b416-4014-8e6f-12417863e4d4?mode=design&machineId=30dffcdd-16c2-49e2-bfc6-a674057cb271" title="层次状态"> <img src="https://github.com/statelyai/xstate/assets/1093738/32b0692b-1c29-4469-b5e3-03146e3ef249" alt="层次状态" width="400" /> <br /> 在 Stately Studio 中打开 </a> <br /> </td> </tr> </tbody> </table>

并行状态机

import { createMachine, createActor } from 'xstate';

const wordMachine = createMachine({
  id: 'word',
  type: 'parallel',
  states: {
    bold: {
      initial: 'off',
      states: {
        on: {
          on: { TOGGLE_BOLD: 'off' }
        },
        off: {
          on: { TOGGLE_BOLD: 'on' }
        }
      }
    },
    underline: {
      initial: 'off',
      states: {
        on: {
          on: { TOGGLE_UNDERLINE: 'off' }
        },
        off: {
          on: { TOGGLE_UNDERLINE: 'on' }
        }
      }
    },
    italics: {
      initial: 'off',
      states: {
        on: {
          on: { TOGGLE_ITALICS: 'off' }
        },
        off: {
          on: { TOGGLE_ITALICS: 'on' }
        }
      }
    },
    list: {
      initial: 'none',
      states: {
        none: {
          on: {
            BULLETS: 'bullets',
            NUMBERS: 'numbers'
          }
        },
        bullets: {
          on: {
            NONE: 'none',
            NUMBERS: 'numbers'
          }
        },
        numbers: {
          on: {
            BULLETS: 'bullets',
            NONE: 'none'
          }
        }
      }
    }
  }
});

const actor = createActor(wordMachine);

actor.subscribe((state) => {
  console.log(state.value);
});

actor.start();
// 日志输出 {
//   bold: 'off',
//   italics: 'off',
//   underline: 'off',
//   list: 'none'
// }

actor.send({ type: 'TOGGLE_BOLD' });
// 日志输出 {
//   bold: 'on',
//   italics: 'off',
//   underline: 'off',
//   list: 'none'
// }

actor.send({ type: 'TOGGLE_ITALICS' });
// 日志输出 {
//   bold: 'on',
//   italics: 'on',
//   underline: 'off',
//   list: 'none'
// }

</td> <td> <a href="https://stately.ai/registry/editor/fa443471-b416-4014-8e6f-12417863e4d4?mode=design&machineId=980f50d8-e1ff-4441-8c8b-afe41c1610f2" title="并行状态"> <img src="https://github.com/statelyai/xstate/assets/1093738/3b1989c0-f4a9-4653-baf2-4df3a40e91a6" alt="并行状态" width="400" /> <br /> 在Stately Studio中打开 </a> </td> </tr> </tbody> </table>

历史状态

import { createMachine, createActor } from 'xstate';

const paymentMachine = createMachine({
  id: 'payment',
  initial: 'method',
  states: {
    method: {
      initial: 'cash',
      states: {
        cash: {
          on: {
            SWITCH_CHECK: 'check'
          }
        },
        check: {
          on: {
            SWITCH_CASH: 'cash'
          }
        },
        hist: { type: 'history' }
      },
      on: { NEXT: 'review' }
    },
    review: {
      on: { PREVIOUS: 'method.hist' }
    }
  }
});

const actor = createActor(paymentMachine);

actor.subscribe((state) => {
  console.log(state.value);
});

actor.start();
// 日志输出 {
//   value: { method: 'cash' },
// }

actor.send({ type: 'SWITCH_CHECK' });
// 日志输出 {
//   value: { method: 'check' },
// }

actor.send({ type: 'NEXT' });
// 日志输出 {
//   value: 'review',
// }

actor.send({ type: 'PREVIOUS' });
// 日志输出 {
//   value: { method: 'check' },
// }

</td> <td> <a href="https://stately.ai/registry/editor/fa443471-b416-4014-8e6f-12417863e4d4?mode=design&machineId=d1a9bb95-db97-4af3-b38b-71b005c643d3" title="历史状态"> <img src="https://github.com/statelyai/xstate/assets/1093738/1be5c495-d560-4660-94f2-5341efbf7128" alt="历史状态" width="400" /> <br /> 在Stately Studio中打开 </a> </td> </tr> </tbody> </table>

赞助商

特别感谢支持这个开源项目的赞助商：

语义化版本政策

我们理解公共契约的重要性，并且不打算在次要或补丁版本中发布任何对运行时API的破坏性更改。我们在对XState库进行任何更改时都会考虑这一点，并努力最小化这些更改对现有用户的影响。

破坏性更改

XState自身执行大量用户逻辑。因此，几乎任何行为的改变都可能被视为破坏性更改。我们认识到这是一个潜在的问题，但认为将每个更改都视为破坏性更改是不切实际的。我们尽最大努力谨慎地实现新功能，使我们的用户能够以更好、更安全的方式实现他们的逻辑。

任何更改_都可能_影响现有XState机器的行为，如果这些机器使用特定配置的话。我们不会随意引入行为变化，并且我们的目标是避免做出影响大多数现有机器的更改。但我们保留在次要版本中做出_某些_行为更改的权利。这样的更改将始终由我们对情况的最佳判断来决定。在决定升级之前，请务必阅读我们的发布说明。

TypeScript更改

我们还保留类似的权利，可以在次要版本中调整声明的TypeScript定义或放弃对旧版TypeScript的支持。TypeScript语言本身发展迅速，并且经常在其次要版本中引入破坏性更改。我们的团队也在不断学习如何更有效地利用TypeScript - 因此类型定义也在不断改进。

由于这些原因，我们的团队不可能受制于在TypeScript旧版本是最新版本时做出的决定，或者当我们不知道如何更好地声明我们的类型时做出的决定。我们不会经常引入声明更改 - 但与运行时更改相比，我们更有可能这样做。

包

XState系列中的大多数包都声明了对XState本身的对等依赖。在发布XState的新版本时，我们会谨慎地维护与已发布包的兼容性，但是依赖于XState的包的每次发布都会调整声明的对等依赖范围以包含XState的最新版本。例如，您应该始终能够更新xstate而无需更新@xstate/react。但是当您更新@xstate/react时，我们强烈建议也更新xstate。