Flutter多功能开发框架插件masamune的使用

Introduction

Masamune Framework是由mathru.net开发的一个Flutter多功能开发框架插件，旨在减少应用程序开发中的大部分编码工作。通过CLI工具生成代码模板和build_runner自动生成额外代码，使开发者能够专注于业务逻辑，同时确保代码的一致性和可维护性。以下是Masamune Framework的一些核心功能：

• CLI代码模板生成
• 自动代码生成
• 路由管理
• 数据库支持（NoSQL）
• 状态管理
• 翻译管理
• 主题管理
• 共享偏好设置
• 表单构建
• UI支持
• Firebase/Firestore集成

[GitHub] | [YouTube] | [Packages] | [Twitter] | [Threads] | [LinkedIn] | [mathru.net]

Installation

安装CLI工具

flutter pub global activate katana_cli

添加Masamune Framework到现有项目

flutter pub add masamune
flutter pub add json_annotation
flutter pub add freezed_annotation
flutter pub add --dev build_runner
flutter pub add --dev masamune_builder
flutter pub add --dev json_serializable
flutter pub add --dev freezed

Project Creation

执行以下命令创建新项目：

katana create [Application ID(e.g. com.test.myapplication)]

这将自动完成以下配置：

• 图片文件放置在assets文件夹下
• 自动生成katana.yaml
• 自动安装所需包
• 自动设置VSCode启动器
• 使用build_runner生成代码

Code Change Monitoring

使用build_runner监控代码变化并自动生成代码：

katana code watch

如果需要手动触发代码生成：

katana code generate

Implementation

Page

创建页面

katana code page [Page name]

页面类示例：

@immutable
@PagePath("test")
class TestPage extends PageScopedWidget {
  const TestPage({super.key});

  static const query = _$TestPageQuery();

  @override
  Widget build(BuildContext context, PageRef ref) {
    return UniversalScaffold();
  }
}

页面跳转

router.push(TestPage.query());
router.replace(TestPage.query());
router.pop();

设置初始页面

final initialQuery = TestPage.query();

Data Model

创建集合模型

katana code collection [Collection name]

集合模型类示例：

@freezed
@formValue
@immutable
@CollectionModelPath("test")
class TestModel with _$TestModel {
  const factory TestModel({
    required String name,
    String? test,
  }) = _TestModel;

  factory TestModel.fromJson(Map<String, Object?> json) => _$TestModelFromJson(json);

  static const document = _$TestModelDocumentQuery();
  static const collection = _$TestModelCollectionQuery();
  static const form = _$TestModelFormQuery();
}

使用模型

final testModelCollection = ref.app.model(TestModel.collection());
testModelCollection.load();

Controller

创建控制器：

katana code controller [Controller name]

控制器类示例：

@Controller(autoDisposeWhenUnreferenced: false)
class TestController extends ChangeNotifier {
  TestController();

  static const query = _$TestControllerQuery();
}

获取控制器：

final testController = ref.page.controller(TestController.query());

State Management

使用ref.app.model和ref.(page/app).controller进行状态管理。

Translation

翻译通过Google Spreadsheet实现：

@GoogleSpreadSheetLocalize(
  "https://docs.google.com/spreadsheets/d/1bw7IXEr7BGkZ4U6on0OuF7HQkTMgDSm6u5ThpBkDPeo/edit#gid=551986808",
  version: 1,
)
class AppLocalize extends _$AppLocalize {}

使用翻译文本：

Text(l().success);

Theme Management

定义主题：

@appTheme
final theme = AppThemeData(
  primary: Colors.blue,
  secondary: Colors.cyan,
  onPrimary: Colors.white,
  onSecondary: Colors.white,
);

使用主题：

return UniversalScaffold(
  appBar: UniversalAppBar(title: Text("Title"), backgroundColor: theme.color.secondary),
  body: UniversalColumn(
    crossAxisAlignment: CrossAxisAlignment.start,
    children:[
      Center(child: CircleAvatar(backgroundImage: theme.asset.userIcon.provider)),
      Text("User Name", style: theme.text.displayMedium)
    ]
  )
);

Form Building

获取表单控制器：

final memo = const MemoModel(title: "", text: "");
final formController = ref.page.form(MemoModel.form(memo));

绘制表单并验证：

FormTextField(
  form: formController,
  onSaved: (value) => formController.value.copyWith(email: value),
),

FormButton(
  "Login",
  onPressed: () async {
    final LoginValue loginValue = formController.validate();
    if (loginValue == null) {
      return;
    }
    try {
      // Normal processing
    } catch (e) {
      // Error handling
    }
  },
),

UI Support

显示对话框：

Modal.alert(
  title: "Title",
  text: "Contents text",
  submitText: "OK",
  onSubmit: () {
    // Processing when the OK button is pressed
  },
);

响应式布局：

return UniversalScaffold(
  breakpoint: Breakpoint.sm,
  sideBar: UniversalSideBar(
    decoration: const BoxDecoration(
      border: Border(right: BorderSide(color: Colors.grey)),
    ),
    children: [
      for (var i = 0; i < 100; i++)
        ListTile(
          tileColor: Colors.blue,
          title: Text((i + 1).toString()),
        ),
    ],
  ),
  appBar: UniversalSliverAppBar(
    title: const Text("UniversalViewPage"),
    subtitle: const Text("UniversalViewPage"),
    titlePosition: UniversalAppBarTitlePosition.bottom,
    background: UniversalAppBarBackground(theme.asset.image.provider),
  ),
  body: UniversalListView(
    onRefresh: () {
      return Future.delayed(1.s);
    },
    padding: const EdgeInsets.only(top: 32),
    children: [
      UniversalColumn(
        children: [
          ...List.generate(100, (i) {
            return ListTile(
              tileColor: Colors.red,
              title: Text((i + 1).toString()),
            );
          }).mapResponsive(sm: 6, md: 4),
        ],
      ),
    ],
  ),
);

Authentication

用户注册和登录：

await appAuth.register(
  EmailAndPasswordAuthQuery.register(
    email: "test@email.com",
    password: "12345678",
  ),
);

await appAuth.signIn(
  EmailAndPasswordAuthQuery.signIn(
    email: "test@email.com",
    password: "12345678",
  ),
);

await appAuth.signOut();

File Storage

上传文件：

final storage = Storage(const StorageQuery("test/file"));

final pickedData = await FilePicker.platform.pickFiles();
storage.upload(pickedData.first.path);

Firebase/Firestore Support

添加Firebase相关包：

flutter pub add katana_auth_firebase
flutter pub add katana_model_firestore
flutter pub add katana_storage_firebase

初始化Firebase：

flutterfire configure

切换适配器：

final modelAdapter = FirestoreModelAdapter(options: DefaultFirebaseOptions.currentPlatform);
final authAdapter = FirebaseAuthAdapter(options: DefaultFirebaseOptions.currentPlatform);
final storageAdapter = FirebaseStorageAdapter(options: DefaultFirebaseOptions.currentPlatform);

示例代码

以下是main.dart的完整示例代码：

import 'package:flutter/material.dart';
import 'package:masamune/masamune.dart';

part 'main.theme.dart';
part 'main.localize.dart';

const title = "";

const initialQuery = null;

const modelAdapter = RuntimeModelAdapter();
const authAdapter = RuntimeAuthAdapter();
const storageAdapter = LocalStorageAdapter();
const functionsAdapter = RuntimeFunctionsAdapter();

@appTheme
final theme = AppThemeData(
  primary: Colors.blue,
  secondary: Colors.cyan,
  onPrimary: Colors.white,
  onSecondary: Colors.white,
);

final router = AppRouter(
  boot: null,
  initialQuery: initialQuery,
  redirect: [],
  pages: [],
);

final l = AppLocalize();

@GoogleSpreadSheetLocalize(
  [
    "https://docs.google.com/spreadsheets/d/1bw7IXEr7BGkZ4U6on0OuF7HQkTMgDSm6u5ThpBkDPeo/edit#gid=551986808"
  ],
  version: 1,
)
class AppLocalize extends _$AppLocalize {}

final appRef = AppRef();

final appAuth = Authentication();

final appFunction = Functions();

const flavor = String.fromEnvironment("FLAVOR");

void main() {
  runMasamuneApp(
    (adapters) => MasamuneApp(
      title: title,
      appRef: appRef,
      theme: theme,
      routerConfig: router,
      localize: l,
      authAdapter: authAdapter,
      modelAdapter: modelAdapter,
      storageAdapter: storageAdapter,
      functionsAdapter: functionsAdapter,
      masamuneAdapters: adapters,
    ),
  );
}

以上是Masamune Framework的核心功能和使用方法，希望对您有所帮助！