一個輕量級且彈性的狀態機框架,專為 Dart 設計,旨在簡化 Flutter 和 Web 應用中的狀態管理。它提供了一種清晰的結構來定義狀態、轉換和動作,以實現可預測且易於維護的應用邏輯。該套件支援同步與非同步轉換,適用於複雜的工作流程,例如表單處理、驗證流程和 UI 導航。設計時著重於簡單性與效能,可無縫整合至現有專案中,無需沉重的依賴。
適用情境
管理複雜的UI工作流程
處理多步驟表單
實現驗證流程
控制應用導航
建模遊戲或流程狀態
主要特色
用於定義狀態和轉換的簡單 API
對同步和異步操作的支援
內建的事件驅動架構
透過自訂守衛和監聽器擴展
輕量且無依賴
適合對象
尋求結構化狀態管理的開發者
需要可預測狀態轉換的專案
具有複雜使用者互動的應用程式
希望減少樣板程式碼的團隊
使用建議
不適合簡單的狀態變更
需要理解狀態機概念
有限的內建除錯工具
最適合具有明確狀態邊界的應用程式
原始 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.