# npm
npm install xstate
 
# yarn
yarn add xstate
 
# pnpm
pnpm add xstate

# 安装 React 绑定
npm install @xstate/react
 
# 或使用 pnpm
pnpm add @xstate/react

<script src="https://cdn.jsdelivr.net/npm/xstate@5/dist/xstate.min.js"></script>

import { createMachine, createActor } from 'xstate';
 
// 1. 定义状态机
const toggleMachine = createMachine({
  id: 'toggle',
  initial: 'inactive',
  states: {
    inactive: {
      on: { TOGGLE: 'active' }
    },
    active: {
      on: { TOGGLE: 'inactive' }
    }
  }
});
 
// 2. 创建 Actor 实例
const toggleActor = createActor(toggleMachine);
 
// 3. 订阅状态变化
toggleActor.subscribe((snapshot) => {
  console.log('当前状态:', snapshot.value);
});
 
// 4. 启动 Actor
toggleActor.start();
// 输出: "当前状态: inactive"
 
// 5. 发送事件触发状态转换
toggleActor.send({ type: 'TOGGLE' });
// 输出: "当前状态: active"
 
toggleActor.send({ type: 'TOGGLE' });
// 输出: "当前状态: inactive"

import { createMachine, createActor, fromPromise, assign } from 'xstate';
 
const fetchMachine = createMachine({
  id: 'fetch',
  initial: 'idle',
  context: {
    data: null,
    error: null,
    retries: 0
  },
  states: {
    idle: {
      on: { FETCH: 'loading' }
    },
    loading: {
      invoke: {
        id: 'fetchData',
        src: fromPromise(({ input }) => fetch(input.url).then(r => r.json())),
        onDone: {
          target: 'success',
          actions: assign({
            data: ({ event }) => event.output
          })
        },
        onError: {
          target: 'failure',
          actions: assign({
            error: ({ event }) => event.error,
            retries: ({ context }) => context.retries + 1
          })
        }
      }
    },
    success: { type: 'final' },
    failure: {
      on: {
        RETRY: {
          target: 'loading',
          actions: assign({ retries: ({ context }) => context.retries + 1 })
        }
      }
    }
  }
});

// Actor 逻辑创建器
import { fromPromise, fromCallback, fromObservable, fromTransition } from 'xstate';
 
// Promise Actor
const fetchDataActor = fromPromise(async ({ input }) => {
  const response = await fetch(input.url);
  return response.json();
});
 
// Callback Actor（用于 WebSocket 等）
const websocketActor = fromCallback(({ receive, sendBack }) => {
  const ws = new WebSocket('wss://example.com');
  ws.onmessage = (event) => sendBack(event.data);
  receive((event) => ws.send(event.value));
  return () => ws.close();
});

import { setup, createActor, fromPromise } from 'xstate';
 
const machine = setup({
  types: {} as {
    context: { userId: string; data: any };
    events:
      | { type: 'LOGIN'; userId: string }
      | { type: 'LOGOUT' }
      | { type: 'DATA_LOADED'; data: any };
  },
  actors: {
    fetchData: fromPromise(async ({ input }: { input: { userId: string } }) => {
      const res = await fetch(`/api/data/${input.userId}`);
      return res.json();
    })
  }
}).createMachine({
  id: 'auth',
  initial: 'idle',
  context: { userId: '', data: null },
  states: {
    idle: { /* ... */ },
    loading: { /* ... */ }
  }
});

import { createBrowserInspector } from '@statelyai/inspect';
 
const inspector = createBrowserInspector();
const actor = createActor(machine, { inspect: inspector.inspect });
actor.start();

const machine = createMachine({
  id: 'app',
  initial: 'dashboard',
  states: {
    dashboard: {
      type: 'parallel', // 并行状态：多个子状态同时活跃
      states: {
        analytics: {
          initial: 'loading',
          states: {
            loading: { /* ... */ },
            loaded: { /* ... */ },
            error: { /* ... */ }
          }
        },
        notifications: {
          initial: 'unread',
          states: {
            unread: { /* ... */ },
            read: { /* ... */ }
          }
        }
      }
    }
  }
});

const parentMachine = createMachine({
  id: 'orchestrator',
  invoke: [
    // 并行的子 Actor
    { id: 'auth', src: authActor },
    { id: 'dataSync', src: syncActor }
  ],
  on: {
    'auth.LOGGED_IN': {
      actions: sendTo('dataSync', { type: 'START_SYNC' })
    }
  }
});

const machine = createMachine({
  id: 'notification',
  initial: 'visible',
  states: {
    visible: {
      after: {
        // 3 秒后自动转换到隐藏状态
        3000: 'hidden'
      }
    },
    hidden: { type: 'final' }
  }
});

// 获取可序列化的快照
const snapshot = actor.getSnapshot();
const serialized = JSON.stringify(snapshot);
 
// 恢复状态
const restored = createActor(machine, {
  snapshot: JSON.parse(serialized)
});
restored.start();

import { createActor } from 'xstate';
import { toggleMachine } from './machines';
 
it('should toggle to active on TOGGLE event', () => {
  const actor = createActor(toggleMachine);
  actor.start();
  
  expect(actor.getSnapshot().value).toBe('inactive');
  
  actor.send({ type: 'TOGGLE' });
  
  expect(actor.getSnapshot().value).toBe('active');
});

// 结账流程示例
const checkoutMachine = createMachine({
  id: 'checkout',
  initial: 'cart',
  states: {
    cart: { on: { NEXT: 'address' } },
    address: { on: { NEXT: 'payment', BACK: 'cart' } },
    payment: {
      invoke: {
        src: 'processPayment',
        onDone: 'review',
        onError: 'paymentError'
      }
    },
    review: { on: { CONFIRM: 'confirming', BACK: 'payment' } },
    confirming: {
      invoke: {
        src: 'confirmOrder',
        onDone: 'success',
        onError: 'confirmError'
      }
    },
    success: { type: 'final' }
  }
});

// 搜索框：取消旧请求、防抖
const searchMachine = createMachine({
  id: 'search',
  initial: 'idle',
  context: { query: '', results: [] },
  states: {
    idle: {
      on: { INPUT: { target: 'debouncing', actions: assign({ query: ... }) } }
    },
    debouncing: {
      after: { 300: 'loading' },
      on: { INPUT: { target: 'debouncing', actions: assign({ query: ... }) } }
    },
    loading: {
      invoke: {
        id: 'searchAPI',
        src: fromPromise(({ input }) => searchAPI(input.query)),
        onDone: { target: 'results', actions: assign({ results: ... }) },
        onError: 'error'
      },
      // 新输入时自动取消当前请求
      on: { INPUT: { target: 'debouncing' } }
    },
    results: { on: { INPUT: 'debouncing' } },
    error: { on: { RETRY: 'loading', CLEAR: 'idle' } }
  }
});

// 使用 setup() 获得完整的类型推导
import { setup, createActor } from 'xstate';
 
const machine = setup({
  types: {} as {
    context: { count: number };
    events:
      | { type: 'INCREMENT' }
      | { type: 'DECREMENT' }
      | { type: 'RESET' };
    input: {} as { initialCount?: number };
  }
}).createMachine({
  id: 'counter',
  initial: 'active',
  context: ({ input }) => ({
    count: input.initialCount ?? 0
  }),
  states: {
    active: {
      on: {
        INCREMENT: { actions: assign({ count: ({ context }) => context.count + 1 }) },
        DECREMENT: { actions: assign({ count: ({ context }) => context.count - 1 }) },
        RESET: { actions: assign({ count: 0 }) }
      }
    }
  }
});
 
// 类型安全的使用
const actor = createActor(machine, { input: { initialCount: 10 } });
actor.start();
actor.send({ type: 'INCREMENT' }); // ✅ 类型检查通过
// actor.send({ type: 'INVALID' }); // ❌ TypeScript 编译错误

import { createActor } from 'xstate';
import { assert } from 'xstate/assert';
 
// 使用 xstate-test 进行测试生成
import { createTestModel } from 'xstate/test';
import { myMachine } from './machines';
 
const model = createTestModel(myMachine);
 
model.testPath(
  { states: ['idle', 'loading'], events: ['FETCH'] },
  async ({ snapshot, event }) => {
    const actor = createActor(myMachine);
    actor.start();
    actor.send(event);
    expect(actor.getSnapshot().value).toBe('loading');
  }
);

// ✅ 使用 setup() 进行类型安全定义
const machine = setup({
  types: {} as { context: {...}; events: ... }
}).createMachine({ ... });
 
// ✅ 将 Actor 逻辑与 UI 分离
// machines/checkout.ts
export const checkoutMachine = createMachine({ ... });
 
// components/Checkout.tsx
const actor = useActor(checkoutMachine);
 
// ✅ 使用 fromPromise / fromCallback 封装副作用
const apiActor = fromPromise(async ({ input }) => {
  return await api.getData(input.id);
});
 
// ✅ 使用 useSelector 优化 React 渲染
const status = useSelector(actor, (snapshot) => snapshot.value);
 
// ✅ 为复杂状态机编写状态图可视化
// 使用 Stately Studio 或 @statelyai/inspect