Flutter核心功能扩展插件mustang_core的使用

Mustang 是一个用于构建Flutter应用程序的框架，提供了许多开箱即用的功能，如状态管理、持久化、缓存、事件管理和切面编程等。本文将详细介绍如何使用 mustang_core 插件，并提供完整的示例代码。

目录

• 框架组件
• 组件通信
• 模型
• 状态
• 服务
• 屏幕
• 持久化
• 缓存
• 事件
• 切面
• 项目结构
• 快速开始

框架组件

Mustang框架由以下几个主要组件构成：

• Model：定义视图所需的数据。
• Screen：Flutter小部件，可以嵌入到其他屏幕上。
• State：允许访问与关联屏幕指定的模型。
• Service：定义与关联屏幕相关的数据获取操作和业务逻辑。

组件通信

每个 Screen 都与一个 Service 和一个 State 关联。以下是 Screen 的生命周期步骤：

1. Screen 在构建UI时读取 State。
2. Screen 响应用户事件（如滚动、点击等）调用 Service 中的方法。
3. Service：
   • 读取/更新 Models，并由 MustangStore 管理。
   • 根据需要进行API调用。
   • 当 Models 被修改时通知 State。
4. State 通知 Screen 重新构建UI。
5. 返回步骤1。

模型

模型是一个抽象类，标注为 @appModel，名称以 $ 开头。字段通过 InitField 注解初始化。

@appModel
abstract class $User {
  late String name;
  late int age;
  @InitField(false)
  late bool admin; 
  @WireNameField('postalCode')  
  late int zip;
  @InitField(['user', 'default'])
  late BuiltList<String> roles;
  late $Address address;  
  late BuiltList<$Vehicle> vehicles;  
  @InitField('')
  @SerializeField(false)  
  late String errorMsg; 
}

状态

状态是一个抽象类，标注为 @screenState，名称以 $ 开头，仅允许模型作为字段。

@screenState
abstract class $ExampleScreenState {
  late $User user; 
  late $Vehicle vehicle; 
}

服务

服务是一个抽象类，标注为 @screenService，名称以 $ 开头。服务具有以下API：

• updateState：更新模型并触发屏幕重建。
• memoizeScreen：调用方法仅执行一次。
• clearMemoizedScreen：清除缓存的数据。

@screenService
abstract class $ExampleScreenService {
  void getUser() {
    User user = MustangStore.get<User>() ?? User();
    updateState1(user);
  }
}

屏幕

每个 Screen 应该是 MustangScreen 小部件的顶级小部件。

Widget build(BuildContext context) {
  return MustangScreen<CounterState>(
    state: CounterState(context: context),
    builder: (BuildContext context, CounterState state) {
      int counter = state.counter.value;
      return Center(
        child: Column(
          children: [
            Padding(
              padding: const EdgeInsets.all(8.0),
              child: Text('$counter'),
            ),
            // ...
          ],
        ),
      );
    },
  );
}

持久化

默认情况下，模型仅保存在内存中。为了持久化数据，可以在 main.dart 中配置持久化：

WidgetsFlutterBinding.ensureInitialized();
Directory dir = await getApplicationDocumentsDirectory();
await MustangStore.configPersistence(UnifiedConstants.persistentStoreName, dir.path);
await MustangStore.restoreState(app_serializer.json2Type, app_serializer.serializerNames);

缓存

缓存允许在需要时切换同一类型的实例。每个服务实例都有以下缓存相关API：

Future<void> addObjectToCache<T>(String key, T t);
Future<void> deleteObjectsFromCache(String key);
static Future<void> restoreObjects(
    String key,
    void Function(void Function<T>(T t) update, String modelName, String jsonStr,) callback,
);
bool itemExistsInCache(String key);

事件

事件用于处理应用中的各种事件，如互联网连接事件、服务器数据更新事件等。创建事件模型时需要标注 @appEvent。

@appModel
@appEvent
abstract class $TimerEvent {
  @InitField(0)
  late int value;
}

// 订阅事件
Widget build(BuildContext context) {
  return MaterialApp(
    navigatorObservers: [
      MustangRouteObserver.getInstance(),
    ],
  );
}

// 发布事件
connectivity_plus.Connectivity().onConnectivityChanged.listen((var connectivityResult) {
    EventStream.pushEvent(mustangAppConfig);
});

切面

切面是定义在方法上的钩子，可以改变执行流。Mustang支持三种切面类型：Before、After 和 Around。

@aspect
abstract class $BeforeAspectExample {
  @invoke
  Future<void> run(Map<String, dynamic> args) async { }
}

@Before([r'$BeforeAspectExample'], args: {'one': 1, 'two': 2.2})
Future<void> requestCode() async { }

项目结构

项目结构如下：

lib/
  - main.dart
  - src
    - models/
      - model1.dart
      - model2.dart
    - screens/
      - first/
        - ext/
          - first_extension_service.dart
          - second_extension_service.dart
        - widgets/
          - first_widget.dart
          - second_widget.dart
        - first_screen.dart
        - first_state.dart
        - first_service.dart
      - second/
        - ext/
          - first_extension_service.dart
          - second_extension_service.dart
        - widgets/
          - first_widget.dart
          - second_widget.dart
        - second_screen.dart
        - second_state.dart
        - second_service.dart

快速开始

以下是如何快速开始使用 mustang_core 创建一个简单的计数器应用：

安装依赖

mkdir -p ~/lib && cd ~/lib
git clone https://github.com/flutter/flutter.git -b stable
export PATH=$PATH:~/lib/flutter/bin
export PATH=$PATH:~/.pub-cache/bin
dart pub global activate open_mustang_cli
cd /tmp
flutter create quick_start
cd quick_start
flutter pub get
omcli -s counter
omcli -w

更新模型、屏幕和服务

// counter.model.dart
@appModel 
abstract class $Counter {
  @InitField(0)
  late int value;
}

// counter_screen.dart
import 'package:flutter/material.dart';
import 'package:mustang_widgets/mustang_widgets.dart';
import 'counter_service.service.dart';
import 'counter_state.state.dart';

class CounterScreen extends StatelessWidget {
  const CounterScreen({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MustangScreen<CounterState>(
      state: CounterState(context: context),
      builder: (BuildContext context, CounterState state) {
        int counter = state.counter.value;
        return Scaffold(
          appBar: AppBar(title: const Text('Hello Mustang')),
          body: Center(
            child: Column(
              children: [
                Padding(
                  padding: const EdgeInsets.all(8.0),
                  child: Text('$counter'),
                ),
                ElevatedButton(
                  onPressed: CounterService().increment,
                  child: const Text('Increment'),
                ),
              ],
            ),
          ),
        );
      },
    );
  }
}

// counter_service.dart
import 'package:mustang_core/mustang_core.dart';
import 'package:quick_start/src/models/counter.model.dart';

@screenService
abstract class CounterService {
  void increment() {
    Counter counter = MustangStore.get<Counter>() ?? Counter();
    counter = counter.rebuild((b) => b.value = (b.value ?? 0) + 1);
    updateState1(counter);
  }
}

更新 main.dart

import 'package:flutter/material.dart';
import 'src/screens/counter/counter_screen.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: CounterScreen(),
    );
  }
}

通过以上步骤，您已经成功创建了一个使用 mustang_core 的简单计数器应用。希望这些信息对您有所帮助！