# boxes-flutter **Repository Path**: sunlunchang/boxes-flutter ## Basic Information - **Project Name**: boxes-flutter - **Description**: flutter基础开发框架 - **Primary Language**: Dart - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 3 - **Forks**: 3 - **Created**: 2021-06-06 - **Last Updated**: 2025-12-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Boxes Flutter [![pub package](https://img.shields.io/badge/pub-v0.4.7-blue.svg)](https://gitee.com/sunlunchang/boxes_flutter) [![Flutter](https://img.shields.io/badge/flutter-%3E%3D3.0.5-blue.svg)](https://flutter.dev/) [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) 一个功能丰富的 Flutter 开发框架，提供 MVVM 架构支持、实用工具类、响应式编程组件等，帮助开发者快速构建高质量的 Flutter 应用。 [English](README_EN.md) | 简体中文 ## ✨ 特性 - 🏗️ **MVVM 架构** - 完整的 MVVM 架构支持，包含 BaseVm、VmSub 等组件 - 📦 **丰富的工具类** - 日期、文本、金额、数字、加密、正则等实用工具 - 🎨 **主题管理** - 统一的颜色、尺寸、样式管理 - 🔄 **响应式编程** - ObservableField 等响应式数据绑定组件 - 📄 **分页支持** - PageModel 分页模型和工具类 - 🌐 **国际化** - 内置 l10n 国际化支持 - 🎯 **路由管理** - 便捷的路由导航工具 - 📱 **屏幕适配** - 屏幕尺寸适配工具 ## 📦 安装 在 `pubspec.yaml` 文件中添加依赖： ```yaml dependencies: boxes_flutter: git: url: https://gitee.com/sunlunchang/boxes_flutter.git ref: master ``` 然后运行： ```bash flutter pub get ``` ## 🚀 快速开始 ### MVVM 架构使用 ```dart import 'package:boxes_flutter/flutter/slc/mvvm/base_mvvm.dart'; import 'package:provider/provider.dart'; // 1. 创建 ViewModel class HomeVm extends BaseVm { String title = 'Hello Flutter'; void updateTitle(String newTitle) { title = newTitle; notifyListeners(); // 通知视图更新 } } // 2. 创建 View class HomeView extends MvvmStatelessWidget { HomeView({Key? key}) : super(key: key); @override Widget build(BuildContext context) { registerEvent(context, listen: true); final vm = getVm(); return Scaffold( appBar: AppBar(title: Text(vm.title)), body: Center( child: ElevatedButton( onPressed: () => vm.updateTitle('Updated!'), child: Text('Update Title'), ), ), ); } } // 3. 使用 Provider ChangeNotifierProvider( create: (_) => HomeVm(), child: HomeView(), ) ``` ### 响应式字段使用 ```dart import 'package:boxes_flutter/flutter/slc/code/observable_field.dart'; class CounterVm extends BaseVm { final counter = ObservableInt(value: 0); final userName = ObservableField(value: 'Guest'); void increment() { counter.value++; } void updateName(String name) { userName.setValue(name); } } ``` ### 日期工具使用 ```dart import 'package:boxes_flutter/flutter/slc/common/date_util.dart'; // 格式化当前时间 String now = DateUtil.getNowDateStr(); // 输出: 2025-10-14 12:30:45 // 自定义格式 String formatted = DateUtil.formatDate( DateTime.now(), format: DateFormats.zh_y_mo_d_h_m, ); // 输出: 2025年10月14日 12时30分 // 获取星期几 String weekday = DateUtil.getWeekday( DateTime.now(), languageCode: 'zh', short: true, ); // 输出: 周二 ``` ### 文本工具使用 ```dart import 'package:boxes_flutter/flutter/slc/common/text_util.dart'; // 每隔4位加空格 String card = TextUtil.formatSpace4('6222021234567890'); // 输出: 6222 0212 3456 7890 // 格式化金额（每3位加逗号） String amount = TextUtil.formatComma3(1234567); // 输出: 1,234,567 // 隐藏手机号中间4位 String phone = TextUtil.hideNumber('13812345678'); // 输出: 138****5678 // 字符串格式化 String result = TextUtil.format('Hello %s, you have %s messages', ['Alice', '5'] ); // 输出: Hello Alice, you have 5 messages ``` ### 金额工具使用 ```dart import 'package:boxes_flutter/flutter/slc/common/money_util.dart'; // 分转元 String yuan = MoneyUtil.changeF2Y(12345); // 输出: 123.45 // 分转元（带单位） String yuanWithUnit = MoneyUtil.changeF2YWithUnit( 12345, format: MoneyFormat.END_INTEGER, unit: MoneyUnit.YUAN_ZH, ); // 输出: 123.45元 // 元转分 int fen = MoneyUtil.changeY2F(123.45); // 输出: 12345 ``` ### 分页模型使用 ```dart import 'package:boxes_flutter/flutter/slc/adapter/page_model.dart'; // 创建分页模型 PageModel pageModel = PageModel( current: 1, size: 20, total: 100, pages: 5, records: userList, ); // 判断是否最后一页 bool isLast = pageModel.isLastPageSafe(); // 获取非空列表 List users = pageModel.getListNoNull(); // 分页工具类使用 List pageNumbers = PageUtils.rainbow(2, 10, displayCount: 5); // 输出: [1, 2, 3, 4, 5] // 列表分页 List items = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']; List page1 = PageUtils.page(1, 3, items); // 输出: ['a', 'b', 'c'] ``` ## 📚 模块说明 ### MVVM 架构 (`mvvm/`) - **BaseVm** - ViewModel 基类，继承自 ChangeNotifier - **VmSub** - ViewModel 子模块，用于解耦业务逻辑 - **MvvmStatelessWidget** - 无状态 MVVM 组件基类 - **MvvmState** - 有状态 MVVM 组件基类 - **FastMvvm** - 快速 MVVM 实现 - **StatusWidget** - 状态组件（加载中、错误、空数据等） ### 工具类 (`common/`) #### 日期时间 - **DateUtil** - 日期时间格式化、解析、计算 - **TimelineUtil** - 时间轴工具 - **TimerUtil** - 定时器工具 #### 文本处理 - **TextUtil** - 文本格式化、隐藏、分割等 - **RegexUtil** - 正则表达式验证（手机、邮箱、身份证等） #### 数值处理 - **MoneyUtil** - 金额格式化、分元转换 - **NumUtil** - 数字计算、格式化 - **SlcNumUtil** - 扩展数字工具 #### 加密与编码 - **EncryptUtil** - 加密解密工具（MD5、AES、Base64等） - **JsonUtil** - JSON 序列化工具 #### 其他工具 - **ObjectUtil** - 对象判空、比较等 - **RandomUtil** - 随机数生成 - **LogUtil** - 日志工具 - **SpCacheUtil** - SharedPreferences 缓存工具 - **SlcFileUtil** - 文件操作工具 - **SlcUrlUtil** - URL 处理工具 - **AwaitExeUtils** - 异步执行工具 ### 响应式编程 (`code/`) - **ObservableField** - 泛型可观察字段 - **ObservableInt** - 整型可观察字段 - **ObservableDouble** - 浮点型可观察字段 - **ObservableBool** - 布尔型可观察字段 - **ReadObservableField** - 只读可观察字段 - **ValueWrapper** - 值包装器 ### 适配器 (`adapter/`) - **PageModel** - 分页数据模型 - **PageUtils** - 分页工具类（彩虹分页算法、列表分页等） - **SelectBox** - 选择框组件 - **LoadMoreFormat** - 加载更多格式化 ### UI 资源 (`res/`) - **SlcColors** - 颜色定义 - **Dimens** - 尺寸定义 - **Styles** - 样式定义 - **ThemeExtension** - 主题扩展 - **ThemeUtil** - 主题工具 ### 路由管理 (`router/`) - **SlcRouter** - 路由管理器 - **RouterVm** - 路由 ViewModel ### 网络 (`network/`) - **ApiConstant** - API 常量定义 ### 对话框 (`dialog/`) - **DialogLoadingVm** - 加载对话框 ViewModel ## 🎯 实体类 (`common/entity/`) - **KeyValue** - 键值对 - **LabelValue** - 标签值对 - **ValueWrap** - 值包装 - **QDateInfo** - 日期信息 - **ByteSizeFormat** - 字节大小格式化 ## 📖 API 文档 详细的 API 文档请参考各个模块的源码注释。主要类都包含详细的文档注释说明。 ## 🤝 贡献 欢迎提交 Issue 和 Pull Request！ ## 📄 许可证 本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件 ## 👤 作者 **sunlunchang** - 主页: [https://gitee.com/sunlunchang/boxes_flutter](https://gitee.com/sunlunchang/boxes_flutter) ## 🙏 致谢 本项目部分代码参考了以下优秀开源项目： - [Sky24n](https://github.com/Sky24n) - 日期、文本、金额等工具类的部分实现 ## 📝 更新日志 查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新历史。 --- 如果这个项目对你有帮助，请给一个 ⭐️ Star 支持一下！