xstate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

XState v5 Skill

XState v5 技能

CRITICAL: This skill covers XState v5 ONLY. Do not use v4 patterns, APIs, or documentation. XState v5 requires TypeScript 5.0+.

重要提示：本技能仅涵盖 XState v5。请勿使用 v4 的模式、API 或文档。XState v5 需要 TypeScript 5.0+。

When to Use

适用场景

State machine and statechart design
Actor system implementation
XState v5 API usage (
```
setup
```
,
```
createMachine
```
,
```
createActor
```
)
Framework integration (React, Vue, Svelte)
Complex async flow orchestration

状态机与状态图设计
Actor 系统实现
XState v5 API 使用（
```
setup
```
、
```
createMachine
```
、
```
createActor
```
）
框架集成（React、Vue、Svelte）
复杂异步流程编排

Key Concepts

核心概念

Actors are independent entities that communicate by sending messages. XState v5 supports:

Actor Type	Creator	Use Case
State Machine	`createMachine()`	Complex state logic with transitions
Promise	`fromPromise()`	Async operations (fetch, timers)
Callback	`fromCallback()`	Bidirectional streams (WebSocket, EventSource)
Observable	`fromObservable()`	RxJS streams
Transition	`fromTransition()`	Reducer-like state updates

Actor 是通过发送消息进行通信的独立实体。XState v5 支持以下类型：

Actor 类型	创建函数	适用场景
状态机	`createMachine()`	带有状态转换的复杂状态逻辑
Promise	`fromPromise()`	异步操作（请求、定时器）
回调	`fromCallback()`	双向流（WebSocket、EventSource）
可观察对象	`fromObservable()`	RxJS 流
转换	`fromTransition()`	类似Reducer的状态更新

Quick Start

快速开始

typescript

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

const machine = setup({
  types: {
    context: {} as { count: number },
    events: {} as { type: 'increment' } | { type: 'decrement' },
  },
  actions: {
    increment: assign({ count: ({ context }) => context.count + 1 }),
    decrement: assign({ count: ({ context }) => context.count - 1 }),
  },
}).createMachine({
  id: 'counter',
  initial: 'active',
  context: { count: 0 },
  states: {
    active: {
      on: {
        increment: { actions: 'increment' },
        decrement: { actions: 'decrement' },
      },
    },
  },
});

// Create and start actor
const actor = createActor(machine);
actor.subscribe((snapshot) => console.log(snapshot.context.count));
actor.start();
actor.send({ type: 'increment' });

typescript

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

const machine = setup({
  types: {
    context: {} as { count: number },
    events: {} as { type: 'increment' } | { type: 'decrement' },
  },
  actions: {
    increment: assign({ count: ({ context }) => context.count + 1 }),
    decrement: assign({ count: ({ context }) => context.count - 1 }),
  },
}).createMachine({
  id: 'counter',
  initial: 'active',
  context: { count: 0 },
  states: {
    active: {
      on: {
        increment: { actions: 'increment' },
        decrement: { actions: 'decrement' },
      },
    },
  },
});

// 创建并启动Actor
const actor = createActor(machine);
actor.subscribe((snapshot) => console.log(snapshot.context.count));
actor.start();
actor.send({ type: 'increment' });

v5 API Changes (NEVER use v4 patterns)

v5 API 变更（绝对不要使用v4模式）

v4 (WRONG)	v5 (CORRECT)
`createMachine()` alone	`setup().createMachine()`
`interpret()`	`createActor()`
`service.start()`	`actor.start()`
`state.matches()`	`snapshot.matches()`
`services: {}`	`actors: {}`
`state.context`	`snapshot.context`

v4（错误用法）	v5（正确用法）
单独使用 `createMachine()`	`setup().createMachine()`
`interpret()`	`createActor()`
`service.start()`	`actor.start()`
`state.matches()`	`snapshot.matches()`
`services: {}`	`actors: {}`
`state.context`	`snapshot.context`

Invoke vs Spawn

Invoke 与 Spawn 对比

invoke: Actor lifecycle tied to state (created on entry, stopped on exit)
spawn: Dynamic actors independent of state transitions

invoke：Actor的生命周期与状态绑定（进入状态时创建，退出状态时停止）
spawn：独立于状态转换的动态Actor

Inspection API (Debugging)

检查API（调试）

typescript

const actor = createActor(machine, {
  inspect: (event) => {
    if (event.type === '@xstate.snapshot') {
      console.log(event.snapshot);
    }
  },
});

Event types:

@xstate.actor

@xstate.event

@xstate.snapshot

@xstate.microstep

typescript

const actor = createActor(machine, {
  inspect: (event) => {
    if (event.type === '@xstate.snapshot') {
      console.log(event.snapshot);
    }
  },
});

事件类型：

@xstate.actor

、

@xstate.event

、

@xstate.snapshot

、

@xstate.microstep

File Organization

文件组织

feature/
├── feature.machine.ts    # Machine definition
├── feature.types.ts      # Shared types (optional)
├── feature.tsx           # React component
└── feature.test.ts       # Machine tests

feature/
├── feature.machine.ts    # 状态机定义
├── feature.types.ts      # 共享类型（可选）
├── feature.tsx           # React组件
└── feature.test.ts       # 状态机测试

Learning Path

学习路径

Level	Focus
Beginner	Counter, toggle machines; `setup()` pattern
Intermediate	Guards, actions, hierarchical states, `fromPromise()`
Advanced	Observable actors, spawning, actor orchestration

级别	重点内容
入门	计数器、切换状态机； `setup()` 模式
中级	守卫、动作、层级状态、 `fromPromise()`
高级	可观察对象Actor、动态生成、Actor编排

Supporting Documentation

配套文档

PATTERNS.md - Guards, actions, actors, hierarchical/parallel states
REACT.md - React hooks (
```
useMachine
```
,
```
useActor
```
,
```
useSelector
```
)
EXAMPLES.md - Complete working examples

PATTERNS.md - 守卫、动作、Actor、层级/并行状态
REACT.md - React钩子（
```
useMachine
```
、
```
useActor
```
、
```
useSelector
```
）
EXAMPLES.md - 完整可运行示例

Resources

资源

Official Docs
Stately Studio - Visual editor

官方文档
Stately Studio - 可视化编辑器