一个轻量级且灵活的状态机框架,专为 Dart 设计,旨在简化 Flutter 和 Web 应用中的状态管理。它提供了一种清晰的结构来定义状态、转换和操作,从而实现可预测且易于维护的应用逻辑。该包支持同步和异步转换,适用于复杂的流程,如表单处理、身份验证流程和 UI 导航。设计时注重简洁性和性能,可无缝集成到现有项目中,无需依赖重型库。
适合场景
管理复杂的UI工作流
处理多步骤表单
实现身份验证流程
控制应用导航
建模游戏或流程状态
主要特点
用于定义状态和转换的简单 API
对同步和异步操作的支持
内置的事件驱动架构
通过自定义守卫和监听器扩展
轻量且无依赖
适合对象
寻求结构化状态管理的开发者
需要可预测状态转换的项目
具有复杂用户交互的应用程序
希望减少样板代码的团队
使用建议
不适合简单的状态变更
需要理解状态机概念
有限的内置调试工具
最适合具有明确状态边界的App
原始 README
以下为关联源码仓库的 README 原文快照,最新内容请访问源码仓库。
State Machine
A simple, yet powerful state machine framework for Dart supporting Flutter and web apps.
This library is open source, stable and well tested. Development happens on GitHub. Feel free to report issues or create a pull-request there. General questions are best asked on StackOverflow.
Follow the installation instructions on dart packages.
Import the package into your Dart code using:
import'package:statemachine/statemachine.dart';
Creating a machine
To create a new state machine instantiate Machine:
final machine = Machine<String>();
The type of the state machine is used to uniquely identify states of the machine. In this simple example we use a String; but typically you would use an enum, a Symbol, or an arbitrary other identifying object.
Defining states
To create states call Machine.newState and store them in variables. Each state needs an identifying key of the declared type, as described above we use a String that helps debugging.
final startState = machine.newState('start');
final activeState = machine.newState('active');
By default, the first state created is also the start state of the machine. It is possible to explicitly create start and stop states of the machine using Machine.newStartState and Machine.newStopState.
Callbacks on states
States support callbacks whenever a state is entered or left.
To start a state machine and set its state to its starting state call Machine.start:
machine.start();
Similarly, you can stop a machine by calling Machine.stop.
Transitioning between states
There are various ways in which your machine can switch states.
Manually triggered transition
From anywhere within your code you can enter a specific state by calling State.enter.
someState.enter();
Depending on context, it might be easier to set the current state using the accessor on the state machine itself:
machine.current = someState;
Alternatively, you can also use the identifying object to set the active state:
machine.current = 'active';
Event triggered transition
You can define transitions between states that are triggered by events using State.onStream. The example below registers for click events when the inactive state is entered. In case of a click event the callback is executed, and the state machine transitions into the new state:
Also, transitions can be triggered by the completion of a future using State.onFuture. Since futures cannot be suspended or cancelled, the future continues to run even if the owning state is deactivated. Should the state be activated, and the future value is already present, then the value is immediately supplied into the callback. Further activations have no effect.
Also, you can automatically trigger callbacks after a timeout using State.onTimeout. The following snippet calls the callback 1 second after the active state is entered and falls back to another state:
Callbacks often contain code to check for additional constraints and update other objects or UI element before entering a different state. See the tooltip example directory for a more complete illustration of the functionality provided by this library.
Nested machines
Machines can be nested. Simply add another machine that gets started when the state is entered, and stopped when the state is left.