javascript-state-machine 状态历史插件完全指南:从记录到回退遍历

原创2026-09-24 23:41:441,638 阅读
文章标签:开发工具

javascript-state-machine 状态历史插件完全指南:从记录到回退遍历

本指南围绕 javascript-state-machine 仓库中的 state-history.md 文档展开,系统讲解 state-machine-history 插件如何为有限状态机追加「历史记忆」能力:记录每一次状态变迁、回退与前进遍历历史、限制历史长度以及自定义历史命名。读完本文,你将能独立为任意状态机实例接入历史功能,并理解其底层实现原理与边界行为。

默认行为:状态机只跟踪「当前状态」

在未启用任何插件时,javascript-state-machine 的状态机只维护一个当前状态。在 src/app.js 中,state 被定义为只读属性,其 setter 直接抛出 'use transitions to change state' 异常,意味着状态只能通过转移(transition)改变,且旧状态不会保留任何记录。

var fsm = new StateMachine({
  init: 'A',
  transitions: [
    { name: 'step', from: 'A', to: 'B' }
  ]
})

fsm.state;   // 'A'
fsm.step();
fsm.state;   // 'B' —— 但 'A' 已经无处可查

如果需要跟踪「从哪里来、经过哪些状态」,就需要引入 state-machine-history 插件。

安装与引入插件

插件可通过 npm 包名引入打包后的产物,对应仓库中的 lib/history.js:

var StateMachineHistory = require('javascript-state-machine/lib/history')

该文件是 webpack 打包生成的 UMD 模块,支持 CommonJS、AMD 与浏览器全局变量(StateMachineHistory)三种加载方式;而插件的真正源码在 src/plugin/history.js,它本身是一个工厂函数:调用后返回一个包含 configure、init、lifecycle、methods、properties 五个部分的插件对象。这与 src/config.js 中 configurePlugins 的约定完全一致——configurePlugins 会先调用插件工厂函数,再调用其 configure 方法完成配置登记。

启用插件并记录状态历史

在构造状态机时,把插件实例放入 plugins 数组即可开启历史记录:

var fsm = new StateMachine({
  init: 'A',
  transitions: [
    { name: 'step', from: 'A', to: 'B' },
    { name: 'step', from: 'B', to: 'C' },
    { name: 'step', from: 'C', to: 'D' }
  ],
  plugins: [
    new StateMachineHistory()     //  <-- 在这里启用插件
  ]
})

fsm.history;        // [ 'A' ]
fsm.step();
fsm.history;        // [ 'A', 'B' ]
fsm.step();
fsm.history;        // [ 'A', 'B', 'C' ]

fsm.clearHistory();

fsm.history;        // [ ]

启用后,状态机实例上会多出一个 history 数组属性。注意两个细节:

  • 初始状态也会被记录:history 的初始值是 [ 'A' ],而不是空数组;
  • clearHistory() 清空历史:清空后当前状态不受影响,状态机仍停留在当前状态,只是历史轨迹被重置。

test/plugin/history.js 中的 history 测试用例验证了记录行为,包括状态回访(如 solid -> liquid -> gas -> liquid)也会如实记录重复状态;history can be cleared 用例(同文件第 32-57 行)则验证了清空操作只清空历史、不动当前状态。

无操作(no-op)转移不会被记录

值得注意的边界行为:如果转移前后状态相同(例如 from: '*', to: '*' 的通配转移),历史不会追加重复记录。原因在 src/jsm.js 的 transit 实现中:只有当 from !== to 时(除非配置了 observeUnchangedState),onEnterState 事件才会被派发,而插件正是挂接在 onEnterState 事件上记录状态的。测试 history does not record no-op transitions(test/plugin/history.js)完整验证了这一行为。

源码视角:历史到底是怎么记下来的

深入 src/plugin/history.js,插件的工作机制可以拆解为三个钩子:

  1. configure:为 back 与 forward 这两个由插件生成的「虚拟转移」注册生命周期事件名(onBeforeHistoryBack、onAfterHistoryForward 等),这样遍历历史时也能触发与普通转移一致的生命周期回调;
  2. init:在状态机实例上初始化两个数组——instance[past](历史栈)与 instance[future](未来栈);
  3. lifecycle:核心记录逻辑。每当生命周期事件为 onEnterState 时执行:
lifecycle: function(instance, lifecycle) {
  if (lifecycle.event === 'onEnterState') {
    instance[past].push(lifecycle.to);                       // 记录进入的目标状态
    if (max && instance[past].length > max)
      instance[past].shift();                                // 超出 max 时从头部丢弃
    if (lifecycle.transition !== back && lifecycle.transition !== forward)
      instance[future].length = 0;                           // 非遍历转移会清空"未来"栈
  }
}

这里有两个关键设计:

  • future(未来栈)在每次正常转移时被清空:这保证了「回退之后再进行新的转移」时,之前回退过的路径被丢弃,未来栈始终只代表「当前状态往前的连续回退链」;
  • shift() 从头部裁剪:配合 max 选项,实现「只保留最近 N 个状态」的环形滑动窗口效果。

插件通过 src/plugin.js 的 plugin.hook 机制接收生命周期事件——observeEvents 在派发每个事件时都会调用 plugin.hook(this, 'lifecycle', args),把插件挂接进转移流程。

遍历历史:historyBack 与 historyForward

除了查看 history 数组,插件还提供了在历史轨迹中前后移动的能力:

var fsm = new StateMachine({
  init: 'A',
  transitions: [
    { name: 'step', from: 'A', to: 'B' },
    { name: 'step', from: 'B', to: 'C' },
    { name: 'step', from: 'C', to: 'D' }
  ],
  plugins: [
    new StateMachineHistory()
  ]
})

fsm.step();
fsm.step();
fsm.step();

fsm.state;    //                  'D'
fsm.history;  // [ 'A', 'B', 'C', 'D' ]

fsm.historyBack();

fsm.state;    //             'C'
fsm.history;  // [ 'A', 'B', 'C' ]

fsm.historyBack();

fsm.state;    //        'B'
fsm.history;  // [ 'A', 'B' ]

fsm.historyForward();

fsm.state;    // 'C'
fsm.history;  // [ 'A', 'B', 'C' ]

遍历是否可行,由两个只读属性决定:

fsm.canHistoryBack;     // true/false —— 历史栈中是否还有可回退的上一状态
fsm.canHistoryForward;  // true/false —— 未来栈中是否还有可前进的状态

其判定逻辑在源码中一目了然(src/plugin/history.js):

  • canHistoryBack:past.length > 1——历史栈中至少要有两个状态才能回退一步;
  • canHistoryForward:future.length > 0——未来栈非空才能前进。

对应的底层实现(同文件第 64-79 行)中,back 会从 past 栈顶弹出两次得到 from 与 to,把 from 压入 future,再调用 this._fsm.transit(back, from, to, <a href="https://link.gitcode.com/i/e8f2cb42667f99c1fbd944b3657e221b" target="_blank">]) 走一遍完整的转移流程;forward 则从当前状态与 future 栈顶构造一次正向转移。若不可遍历(如初始状态直接调用 historyBack),会抛出 Error('no history')。测试 history back and forward([test/plugin/history.js)逐行验证了回退/前进过程中两个栈的此消彼长关系。

遍历历史时的生命周期事件

用 historyBack / historyForward 遍历历史,不是简单地操作数组——它走的是完整转移流程,因此一整套生命周期事件都会照常触发:

var fsm = new StateMachine({
  init: 'A',
  transitions: [
    { name: 'step', from: 'A', to: 'B' },
    { name: 'step', from: 'B', to: 'C' },
    { name: 'step', from: 'C', to: 'D' }
  ],
  methods: {
    onBeforeHistoryBack:    function(lifecycle) { /* ... */ },
    onAfterHistoryBack:     function(lifecycle) { /* ... */ },
    onBeforeHistoryForward: function(lifecycle) { /* ... */ },
    onAfterHistoryForward:  function(lifecycle) { /* ... */ },
    onEnterC:               function(lifecycle) { /* ... */ },
    onLeaveD:               function(lifecycle) { /* ... */ }
  },
  plugins: [
    new StateMachineHistory()
  ]
})

正因为插件在 configure 阶段通过 config.addTransitionLifecycleNames(back) 与 config.addTransitionLifecycleNames(forward)(见 src/config.js)注册了 historyBack、historyForward 作为「转移名」,所以 onBefore<TRANSITION>、onAfter<TRANSITION> 以及 onLeave<STATE>、onEnter<STATE> 系列事件在遍历时全部生效。

测试 history back and forward lifecycle events(test/plugin/history.js)用 LifecycleLogger 完整断言了 historyBack 的事件序列:

onBeforeTransition → onBeforeHistoryBack → onLeaveState → onLeaveD
→ onTransition → onEnterState → onEnterC → onAfterTransition → onAfterHistoryBack

可见遍历历史与普通转移共享同一套事件机制,你可以在回退/前进时无缝复用已有的生命周期逻辑(如状态进入时的渲染、数据加载等)。

限制历史长度:max 选项

默认情况下,历史记录无上限,会一直累积直到被 clearHistory() 清空。如果状态机运行时间长、状态切换频繁,可以限制只保留最近 N 个状态:

var fsm = new StateMachine({
  transitions: [
    { name: 'step', from: 'A', to: 'B' },
    // ...
  ],
  plugins: [
    new StateMachineHistory({ max: 100 })      //  <-- 只保留最近 100 条
  ]
})

max 的实现就是前面提到的 shift() 裁剪逻辑:每次记录新状态后,若 past.length > max,就从数组头部移除最老的记录。测试 history can be limited to N entries(test/plugin/history.js)以 max: 3 验证了窗口效果——连续四次转移后,历史保持为 [ 'liquid', 'gas', 'liquid' ],最早的状态被淘汰。与之对照,history, by default, just keeps growing(同文件第 126-151 行)验证了不设 max 时历史无限增长。

自定义命名:解决命名冲突

如果 history、historyBack 等名称与你的状态机已有属性或方法冲突,可以通过 name 选项整体重命名:

var fsm = new StateMachine({
  init: 'A',
  transitions: [
    { name: 'step', from: 'A', to: 'B' },
    { name: 'step', from: 'B', to: 'C' },
    { name: 'step', from: 'C', to: 'D' }
  ],
  plugins: [
    new StateMachineHistory({ name: 'memory' })
  ]
})

fsm.step();
fsm.step();

fsm.memory;         // [ 'A', 'B', 'C' ]

fsm.memoryBack();
fsm.memory;         // [ 'A', 'B' ]

fsm.memoryForward();
fsm.memory;         // [ 'A', 'B', 'C' ]

fsm.clearMemory();
fsm.memory;         // [ ]

命名规则的派生逻辑位于插件源码开头的选项解析(src/plugin/history.js):

选项 默认值 作用 派生命名示例(name: 'memory')
name(或 past) 'history' 历史栈属性名 memory
future 'future' 未来栈属性名 yonder
— — 清空方法 clearMemory()
— — 回退方法 memoryBack()
— — 前进方法 memoryForward()
— — 回退可用性 canMemoryBack
— — 前进可用性 canMemoryForward

名称经由 src/util/camelize.js 的 camelize 与 camelize.prepended 规范化:无论你传入 'my-history' 还是 'my_history',都会统一转换为驼峰形式,再与 clear、Back、Forward、can 等前缀拼接。测试 history with configurable names(test/plugin/history.js)使用了 { name: 'memory', future: 'yonder' },完整验证了整套自定义命名 API,包括 yonder 未来栈的独立存在。

在工厂模式与既有对象上使用历史插件

历史记录是按实例隔离的——每个状态机实例拥有自己独立的历史与未来栈,互不干扰。这一点在插件的 init 钩子中体现:它作用于单个 instance,为其各自初始化 []。

因此,历史插件可以无缝配合状态机工厂及各种实例化方式:

// 工厂模式:多个实例共享配置、各持历史
var FSM = StateMachine.factory({
  init: 'solid',
  transitions: [
    { name: 'melt',     from: 'solid',  to: 'liquid' },
    { name: 'vaporize', from: 'liquid', to: 'gas'    },
    { name: 'condense', from: 'gas',    to: 'liquid' }
  ],
  plugins: [
    new StateMachineHistory()
  ]
})

var a = new FSM(),
    b = new FSM();

a.melt();  a.vaporize();  a.condense();

a.history;  // [ 'solid', 'liquid', 'gas', 'liquid' ]
b.history;  // [ 'solid' ]  —— b 完全不受 a 影响

test/plugin/history.js 中 history can be used with a state machine factory(第 356-398 行)、history can be used with a singleton state machine applied to existing object(第 402-437 行,验证 StateMachine.apply 应用到既有对象后历史属性照常工作)以及 history can be used with a state machine factory applied to existing class(第 441-491 行)共同确认了插件与仓库支持的三种实例化方式(new StateMachine、StateMachine.apply、StateMachine.factory)的完全兼容性。

使用建议与注意事项

  • 优先用 API 而非直接改数组:history 是普通数组,理论上可直接修改,但直接 push/pop 会破坏历史与未来栈之间的一致性,且无法触发生命周期事件;请始终使用 step() 等转移方法推进状态,用 historyBack()/historyForward() 遍历,用 clearHistory()(或自定义命名的清空方法)重置;
  • 遍历后新转移会截断未来:回退若干步后,若执行任意新的状态转移,future 栈会被清空(historyForward 将不可用),这是刻意设计——保证历史只代表真实发生过的路径;
  • 不可遍历时的异常:在历史栈不足(canHistoryBack 为 false)时调用 historyBack(),或在未来栈为空(canHistoryForward 为 false)时调用 historyForward(),会抛出 no history 错误,调用前应先用对应 can 属性做守卫判断;
  • 命名冲突检查:自定义 name 前,确认派生出的 memory、memoryBack、canMemoryBack 等名称不会与状态机实例上已有的属性/方法(如自定义的 methods、data)冲突。

参考链接

登录后查看全文
javascript-state-machine