javascript-state-machine 状态历史插件完全指南:从记录到回退遍历
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,插件的工作机制可以拆解为三个钩子:
configure:为back与forward这两个由插件生成的「虚拟转移」注册生命周期事件名(onBeforeHistoryBack、onAfterHistoryForward等),这样遍历历史时也能触发与普通转移一致的生命周期回调;init:在状态机实例上初始化两个数组——instance[past](历史栈)与instance[future](未来栈);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)冲突。
参考链接
- 原始文档:docs/state-history.md
- 插件源码:src/plugin/history.js、打包产物:lib/history.js
- 插件机制:src/plugin.js、配置解析:src/config.js
- 转移与事件引擎:src/jsm.js、docs/lifecycle-events.md
- 名称规范化工具:src/util/camelize.js
- 测试用例:test/plugin/history.js