Stately.js 技术文档

1. 安装指南

Stately.js 是一个基于 JavaScript 的有限状态机（FSM）引擎，适用于 Node.js 和浏览器环境。

在 Node.js 环境中，您可以使用 npm 安装 Stately.js：

$ npm install stately.js

并在您的项目中包含它：

var Stately = require('stately.js');

或者，您可以使用 bower 安装 Stately.js：

$ bower install --save Stately.js

在浏览器环境中，您可以直接将 Stately.js 添加到文档的头部：

<script type="text/javascript" src="https://raw.github.com/fschaefer/Stately.js/master/Stately.js"></script>
<script type="text/javascript">
    // 使用 Stately
</script>

或者使用异步模块定义（AMD）的方式：

<script type="text/javascript" src="https://raw.github.com/jrburke/requirejs/master/require.js"></script>
<script type="text/javascript">
require(['https://raw.github.com/fschaefer/Stately.js/master/Stately.js'], function (Stately) {
    // 使用 Stately
});
</script>

2. 项目使用说明

创建新的状态机

可以使用 new 操作符或工厂方法创建一个新的状态机：

var machine = new Stately(statesObject, initialStateName);

或者

var machine = Stately.machine(statesObject, initialStateName);

两者都会返回一个新的 stateMachine 对象，所有状态的事件都会附加到这个对象上。状态机会转换到初始状态 initialStateName，如果没有提供 initialStateName，则会转换到第一个附加的状态对象。

statesObject 是一个包含 stateObject 对象属性的对象。statesObject 的属性名是状态机的状态。附加的 stateObject 对象用来模拟状态机的状态，属性名是事件，连接的函数是动作：

var machine = Stately.machine({
    'STATE0': {
        event: function () {
            ...
        }
    },
    'STATE1': {
        event: function () {
            ...
        }
    },
    'STATE2':{
        event: function () {
            ...
        },
        anotherEvent: function () {
            ...
        }
    }
});

如果不同状态使用相同的事件标识符的事件，这些事件会链接起来，状态机将处理当前状态中正确的事件（如果有）。如果当前状态中没有处理该事件，它将被忽略。

如果不需要立即声明动作，可以将期望的转换状态直接附加到事件上：

var machine = Stately.machine({
    'STATE0': {
        'event':        /* => */ 'STATE1'
    },
    'STATE1': {
        'event':        /* => */ 'STATE2'
    },
    'STATE2': {
        'event':        /* => */ 'STATE0',
        'anotherEvent': /* => */ 'STATE1'
    }
});

转换

动作可以通过以下几种方式转换状态机到另一个状态：

• 返回期望的下一个状态
• 对于异步动作，使用 setMachineState 方法

在动作中，this 引用了内部 stateStore，可以用来访问其他状态：

...

'STATE1': {
    doSomething: function () {

        ...

        // 从 STATE1 转换到 STATE2
        return this.STATE2;
    }
}

...

如果动作不希望转换状态机到另一个状态，可以省略返回值（或者返回当前状态）。

有时动作需要返回值，这时返回值必须是包含两个元素的数组。第一个元素是状态机应该转换到的状态，第二个元素是返回值：

...

'STATE1': {
    doSomething: function () {

        ...

        // 从 STATE1 转换到 STATE2 并返回一个字符串
        return [this.STATE2, '这是返回值'];
    }
}

...

对于异步动作，可以使用 getMachineState 和 setMachineState 方法：

...

'STATE1': {
    doSomething: function () {
        var self = this;

        setTimeout(function () {

            ...

            self.setMachineState(self.STATE2);
        }, 5000);

        ...

    }
}

...

由于 this 引用了 stateStore，也可以从另一个状态调用动作：

...

'STATE1': {
    doSomething: function () {

        ...

        this.STATE2.doSomethingDifferent.call(this);

        ...

        return this.STATE3.doSomethingCompletelyDifferent.call(this);
    }
}

...

特殊事件钩子函数

有时，当状态机转换到另一个状态时，获得通知很有用。因此，有一些特殊事件名称保留用于事件函数，例如 onEnter、onLeave（进入/离开状态时触发），onBefore<eventname> 和 onAfter<eventname>（在调用事件之前或之后触发）。

这些事件函数的签名如下：

function (event, oldState, newState) {
    ...
}

event - 触发转换的事件。 oldState - 机器转换前的状态。 newState - 机器转换后的状态。

在这些函数中，this 引用了内部的 stateStore。

3. 项目API使用文档

Stately.js 的 API 主要包括以下几个部分：

• Stately - 状态机的构造函数。
• Stately.machine - 创建状态机的工厂方法。
• stateMachine 对象的方法 - getMachineState 和 setMachineState。

以下是一些示例：

// 创建状态机
var machine = Stately.machine({
    'STATE0': {
        event: function () {
            return this.STATE1;
        }
    },
    'STATE1': {
        event: function () {
            return this.STATE2;
        }
    }
});

// 获取当前状态
var currentState = machine.getMachineState();

// 设置新状态
machine.setMachineState('STATE3');

4. 项目安装方式

请参考“安装指南”部分，Stately.js 支持通过 npm 或 bower 在 Node.js 环境中安装，也支持在浏览器环境中直接通过 <script> 标签引入。