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

套件詳情v2.2.0

result_command

使用 result_dart 包實作 Dart 和 Flutter 的命令模式。

AndroidiOSWebmacOSWindowsLinux
近 30 天下載
4760
喜歡數
33
Pub 分數
160

安裝套件

flutter pub add result_command

套件介紹

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

result_command 是一個 Dart 與 Flutter 套件,使用 result_dart 基礎架構實作命令模式。它提供一種結構化的方式,將請求封裝為物件,進而實現更好的關注點分離、取消操作與記錄。此套件專為乾淨架構設計,透過將命令與其執行解耦,提升 Flutter 應用的可測試性與可維護性。該套件可無縫整合至現有的 Dart 程式碼庫,並支援所有主要平台,包括 Android、iOS、Web、macOS、Windows 與 Linux。

適用情境

  • 實現撤銷/重做功能
  • 將使用者介面與業務邏輯分離
  • 建構模組化且可測試的命令鏈
  • 處理帶有結果的異步操作
  • 支援交易工作流程

主要特色

  • 命令模式實現
  • 與 result_dart 的整合
  • 對異步命令的支援
  • 關注點的清晰分離
  • 可擴展且可重用的命令結構

適合對象

  • 使用清潔架構的開發人員
  • 需要強大命令處理功能的團隊
  • 需要事務行為的Flutter應用
  • 強調測試性與可維護性的專案

使用建議

  • 需要熟悉命令模式
  • 依賴 result_dart 套件
  • 可能為簡單使用案例增加開銷

原始 README

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

Result Command

Result Command is a lightweight package that implements the Command Pattern in Flutter, enabling encapsulation of actions, state tracking, and result management.


Installation

Add the package to your pubspec.yaml:

dependencies:
  result_command: x.x.x
  result_dart: 2.x.x

How to Use

1. Creating a Command

Commands encapsulate actions and manage their lifecycle. Depending on the number of parameters your action requires, you can use:

  • Command0: For actions with no parameters.
  • Command1: For actions with one parameter.
  • Command2: For actions with two parameters.

Example:

final fetchGreetingCommand = Command0<String>(
  () async {
    await Future.delayed(Duration(seconds: 2));
    return Success('Hello, World!');
  },
);

final calculateSquareCommand = Command1<int, int>(
  (number) async {
    if (number < 0) {
      return Failure(Exception('Negative numbers are not allowed.'));
    }
    return Success(number * number);
  },
);

2. Listening to a Command

Commands are Listenable, meaning you can react to their state changes:

Using addListener
fetchGreetingCommand.addListener(() {
  final status = fetchGreetingCommand.value;
  if (status is SuccessCommand<String>) {
    print('Success: ${status.value}');
  } else if (status is FailureCommand<String>) {
    print('Failure: ${status.error}');
  }
});
Using ValueListenableBuilder
Widget build(BuildContext context) {
  return ListenableBuilder(
    listenable: fetchGreetingCommand,
    builder: (context, _) {
      return switch (state) {
        RunningCommand<String>() => CircularProgressIndicator(),
        SuccessCommand<String>(:final value) => Text('Success: $value'),
        FailureCommand<String>(:final error) => Text('Failure: $error'),
        _ => ElevatedButton(
          onPressed: () => fetchGreetingCommand.execute(),
          child: Text('Fetch Greeting'),
        ),
      };
    },
  );
}
Using when for Simplified State Handling

The when method simplifies state management by mapping each state to a specific action or value:

fetchGreetingCommand.addListener(() {
  final status = fetchGreetingCommand.value;
  final message = status.when(
    data: (value) => 'Success: $value',
    failure: (exception) => 'Error: ${exception?.message}',
    running: () => 'Fetching...',
    orElse: () => 'Idle',
  );

  print(message);
});

This approach ensures type safety and provides a clean way to handle all possible states of a command.


3. Executing a Command

The execute() method triggers the action encapsulated by the command. During execution, the command transitions through the following states:

  1. Idle: The initial state, indicating the command is ready to execute.
  2. Running: The state while the action is being executed.
  3. Success: The state when the action completes successfully.
  4. Failure: The state when the action fails.
  5. Cancelled: The state when the action is cancelled.

Each command can only be executed one at a time. If another call to execute() is made while the command is already running, it will be ignored until the current execution finishes or is cancelled.

Example:

fetchGreetingCommand.execute();

4. Cancelling a Command

Commands can be cancelled if they are in the Running state. When cancelled, the command transitions to the Cancelled state and invokes the optional onCancel callback.

Example:

final uploadCommand = Command0<void>(
  () async {
    await Future.delayed(Duration(seconds: 5));
  },
  onCancel: () {
    print('Upload cancelled');
  },
);

uploadCommand.execute();

Future.delayed(Duration(seconds: 2), () {
  uploadCommand.cancel();
});

5. Facilitators

To simplify interaction with commands, several helper methods and getters are available:

State Check Getters

These getters allow you to easily check the current state of a command:

  if (command.isRunning) {
    print('Command is idle and ready to execute.');
  }
Cached Values

To avoid flickering or unnecessary updates in the UI, commands cache their last success and failure states:

  • getCachedSuccess(): Retrieves the cached value of the last successful execution, or null if no success is cached.
    final successValue = command.getCachedSuccess();
    if (successValue != null) {
      print('Last successful value: $successValue');
    }
    
  • getCachedFailure(): Retrieves the cached exception of the last failed execution, or null if no failure is cached.
    final failureException = command.getCachedFailure();
    if (failureException != null) {
      print('Last failure exception: $failureException');
    }
    

These facilitators improve code readability and make it easier to manage command states and results efficiently.


6. Filtering Command State

The filter method allows you to derive a new value from the command's state using a transformation function. This is useful for creating filtered or transformed views of the command's state.

Example:
final filteredValue = command.filter<String>(
  'Default Value',
  (state) {
    if (state is SuccessCommand<String>) {
      return 'Success: ${state.value}';
    } else if (state is FailureCommand<String>) {
      return 'Error: ${state.error}';
    }
    return null; // Ignore other states.
  },
);

filteredValue.addListener(() {
  print('Filtered Value: ${filteredValue.value}');
});

This method simplifies state management by allowing you to focus on specific aspects of the command's state.


7. CommandRef

The CommandRef class allows you to create commands that listen to changes in one or more ValueListenables or Streams and execute actions based on derived values.

Example with ValueListenable:
final listenable = ValueNotifier<int>(0);

final commandRef = CommandRef<int, int>(
  (ref) => ref(listenable),
  (value) async => Success(value * 2),
);

commandRef.addListener(() {
  final status = commandRef.value;
  if (status is SuccessCommand<int>) {
    print('Result: ${status.value}');
  }
});

listenable.value = 5; // Executes the command with the value 5.
Example with Stream:
final streamController = StreamController<int>();

final commandRef = CommandRef<int, int>(
  (ref) => ref.stream(streamController.stream, 0), // 0 is the initial value
  (value) async => Success(value * 3),
);

commandRef.addListener(() {
  final status = commandRef.value;
  if (status is SuccessCommand<int>) {
    print('Result: ${status.value}');
  }
});

streamController.add(10); // Executes the command with the value 10.
Features:
  • Automatically listens to changes in ValueListenables using ref(listenable).
  • Converts Streams to synchronous values using ref.stream(stream, initialValue).
  • Executes the action whenever the derived value changes.
  • Processes executions sequentially in a queue to avoid race conditions.
  • Cleans up listeners and stream subscriptions when disposed.

This class is ideal for scenarios where commands need to react dynamically to external state changes from multiple sources.

Documentation

For advanced examples and detailed documentation, visit:


Contribute

We welcome contributions! Feel free to report issues, suggest features, or submit pull requests.

所屬分類

依賴

依賴清單 1 項

原始碼儲存庫

使用此套件的專案

暫無相關資料。