搜尋套件、儲存庫與 APP 分類

套件詳情v3.0.3

state_machine

有限狀態機程式庫。輕鬆定義合法的狀態轉換。監聽狀態進入、離開和轉換。

AndroidiOSWebmacOSWindowsLinux
近 30 天下載
2.4萬
喜歡數
41
Pub 分數
120

安裝套件

flutter pub add state_machine

套件介紹

根據套件公開資料產生的選型評估,僅供參考。

一個用於實現有限狀態機的 Flutter/Dart 庫,讓開發者能輕鬆定義和管理合法的狀態轉換。它提供明確的事件驅動狀態變更,並支援監聽狀態進入、離開和轉換事件。非常適合用於需要確保狀態一致性與可預測行為的複雜工作流程建模。此套件具備平台無關性,支援所有主要的 Flutter 平台。透過將狀態邏輯與 UI 元件分離,促進撰寫乾淨、易維護的程式碼。

適用情境

  • 管理多步驟使用者流程
  • 建模應用程式生命週期狀態
  • 處理非同步工作流程
  • 實作表單驗證狀態機
  • 強制執行業務規則合規

主要特色

  • 事件驅動的狀態轉換
  • 狀態進入/退出/轉換的回調
  • 類型安全的狀態定義
  • 對嵌套和層次狀態的支援
  • 可擴展且可測試的設計

適合對象

  • 開發複雜有狀態應用的開發者
  • 需要確定性狀態管理的團隊
  • 需要對狀態變更進行審計的項目
  • 具有嚴格工作流程規則的應用程式

使用建議

  • 初學者的學習曲線更陡峭
  • 需要仔細規劃狀態圖
  • 在簡單狀態場景中可能引入開銷
  • 有限的內建UI整合

原始 README

以下為關聯原始碼儲存庫的 README 原文快照,最新內容請造訪原始碼儲存庫。

Dart State Machine

Pub Build Status codecov.io documentation

Easily create a finite state machine and define legal state transitions. Listen to state entrances, departures, and transitions.

Getting Started

Import the state_machine package:

import 'package:state_machine/state_machine.dart';
Create a Machine

Once created, the StateMachine will be used to create states and state transitions.

StateMachine light = new StateMachine('light');
Define a Set of States

Use the machine to create all required states. A string name is required for ease of debugging.

State isOn = light.newState('on');
State isOff = light.newState('off');

It's recommended that states be named in the format "is[State]". This may seem strange at first, but it has two main benefits:

  1. It helps differentiate states from transitions, which can be confusing since many words in English are the same as a verb and an adjective ("open" or "secure", for example).
  2. It reads better when calling the state to determine if it's active, as will be demonstrated later.
Define the Legal State Transitions

By defining legal state transitions, you can prevent certain actions based on the current state of the machine. Defining a state transition requires a name (again for ease of debugging), a list of valid "from" states, and the state to transition the machine to.

StateTransition turnOn = light.newStateTransition('turnOn', [isOff], isOn);
StateTransition turnOff = light.newStateTransition('turnOff', [isOn], isOff);
Start the Machine

Before executing any state transitions, the machine should be started at a specific starting state.

light.start(isOff);
Executing a State Transition

The StateTransition class implements Function so that you can simply call a transition to execute it.

light.start(isOff);
turnOn(); // transitions machine from "isOff" to "isOn"
Determining the Active State

The StateMachine instance exposes a current state property which allows you to retrieve the machine's current state at any time.

light.start(isOff);
light.current == isOff; // true

Additionally, the State class implements Function so that you can simply call a state to determine if it's active.

light.start(isOff);
isOff(); // true
isOn();  // false
Listening to State Transitions

The StateTransition class exposes a listen() method that allows you to listen to the transition and receive an event every time the transition executes.

turnOn.listen((StateChange change) {
  print('Light transitioned from ${change.from.name} to ${change.to.name}');
});
light.start(isOff);
turnOn(); // "Light transitioned from off to on"
Passing Data with a State Transition

State transitions accept an optional payload in case you need to pass data along to listeners.

turnOn.listen((StateChange change) {
  print('Light turned on. Wattage: ${change.payload}');
});
light.start(isOff);
turnOn('15w'); // "Light turned on. Wattage: 15w"
Listening for State Entrances and Departures

The State class exposes two streams so that you can listen for the state being entered and the state being left.

isOff.onLeave.listen((StateChange change) {
  print('Left: off');
});
isOn.onEnter.listen((StateChange change) {
  print('Entered: on');
});
light.start(isOff);
turnOn(); // "Left: off"
          // "Entered: on"
Wildcard State and State Transitions

The State class exposes a static instance State.any that can be used as a wildcard when defining a state transition.

StateMachine machine = new StateMachine('machine');
State isFailed = machine.newState('failed');

// This transition will be valid regardless of which state the machine is in.
StateTransition fail = machine.newStateTransition('fail', [State.any], isFailed);
Illegal State Transitions

When you create state transitions, you must define the list of valid "from" states. The machine must be in one of these states in order to execute the transition. If that's not the case, an IllegalStateTransition exception will be thrown.

// Consider a door with the following states and transitions.
StateMachine door = new StateMachine('door');

State isOpen = door.newState('open');
State isClosed = door.newState('closed');
State isLocked = door.newState('locked');

StateTransition open = door.newStateTransition('open', [isClosed], isOpen);
StateTransition close = door.newStateTransition('close', [isOpen], isClosed);
StateTransition lock = door.newStateTransition('lock', [isClosed], isLocked);
StateTransition unlock = door.newStateTransition('unlock', [isLocked], isClosed);

// Let's transition the door from open, to closed, to locked.
door.start(isOpen);
close();
lock();

// In order to open the door, we must first unlock it.
// If we try to open it first, an exception will be thrown.
open(); // throws IllegalStateTransition
Canceling State Transitions

State machines have a set of legal state transitions that are set in stone and provide the required structure. But, there may be scenarios where a state transition may or may not be desirable based on additional logic. To handle this, state transitions support cancellation conditions.

// Consider two state machines - a person and a door.
// The door can be locked or unlocked and the person
// can be with or without a key.
StateMachine door = new StateMachine('door');
State isLocked = door.newState('locked');
State isUnlocked = door.newState('unlocked');
StateTransition unlock = door.newStateTransition('unlock', [isLocked], isUnlocked);

StateMachine person = new StateMachine('person');
State isWithKey = person.newState('withKey');
State isWithoutKey = person.newState('withoutKey');
StateTransition obtainKey = person.newStateTransition('obtainKey', [isWithoutKey], isWithKey);

door.start(isLocked);
person.start(isWithoutKey);

// Add a cancellation condition for unlocking the door:
// If the person is without a key, cancel the unlock transition.
unlock.cancelIf((StateChange change) => isWithoutKey());

unlock(); // false (canceled)
isUnlocked(); // false
obtainKey();
unlock(); // true (not canceled)
isUnlocked(); // true

Example

To run the example:

dart pub global activate webdev
webdev serve example:8080
open http://localhost:8080/

所屬分類

依賴

依賴清單 1 項

  • w_common>=3.0.0 <5.0.0

原始碼儲存庫

使用此套件的專案

暫無相關資料。