fix: add ToastStyle enum and currentStyle property to ToastService

2026-04-08 01:51:02 +08:00
parent b9a39ed2f1
commit cbe11d5db1
209 changed files with 17126 additions and 5 deletions
--- a/lib/README.md
+++ b/lib/README.md
@@ -0,0 +1,739 @@
+# Mom's Kitchen 项目基础支撑库说明
+
+## 项目架构
+
+```
+lib/
+├── main.dart                          # 应用入口
+├── src/
+│   ├── config/                        # 配置文件
+│   │   ├── api_config.dart           # API 配置
+│   │   └── app_config.dart           # 应用配置
+│   ├── l10n/                          # 国际化
+│   │   ├── app_en.arb                # 英文翻译
+│   │   ├── app_zh.arb                # 中文翻译
+│   │   ├── app_zh_Hant.arb           # 繁体中文翻译
+│   │   ├── app_localizations.dart    # 生成的本地化代码
+│   │   ├── app_localizations_en.dart # 英文实现
+│   │   ├── app_localizations_zh.dart # 中文实现
+│   │   └── app_localizations_zh_hant.dart # 繁体中文实现
+│   ├── models/                        # 数据模型
+│   │   └── theme_model.dart          # 主题模型
+│   ├── pages/                         # 页面
+│   │   ├── cart_page.dart            # 购物车页面
+│   │   ├── example_page.dart         # 示例页面
+│   │   ├── home_page.dart            # 首页
+│   │   └── theme_demo_page.dart      # 主题设置页面
+│   ├── services/                      # 服务层
+│   │   ├── api_service.dart          # 网络请求服务
+│   │   ├── app_info_service.dart     # 应用信息服务
+│   │   ├── app_service.dart          # 应用服务（统一管理）
+│   │   ├── animation_service.dart    # 动画管理服务
+│   │   ├── logger_service.dart       # 日志管理服务
+│   │   ├── notification_service.dart # 通知服务
+│   │   ├── orientation_service.dart  # 屏幕方向服务
+│   │   ├── permission_service.dart   # 权限管理服务
+│   │   ├── screen_util_config.dart   # 屏幕适配配置
+│   │   ├── storage_service.dart      # 本地存储服务
+│   │   ├── theme_service.dart        # 主题管理服务
+│   │   └── toast_service.dart        # 消息提示服务
+│   ├── standards/                     # 页面规范
+│   │   ├── app_pages.dart            # 页面注册表
+│   │   ├── page_standards.dart       # 页面规范系统
+│   │   └── page_validator.dart       # 页面验证系统
+│   ├── utils/                         # 工具类
+│   │   ├── app_logger.dart           # 全局日志工具
+│   │   ├── common_utils.dart         # 通用工具
+│   │   ├── date_utils.dart           # 日期工具
+│   │   ├── network_utils.dart        # 网络工具
+│   │   ├── platform_utils.dart       # 平台识别工具
+│   │   └── string_utils.dart         # 字符串工具
+│   └── widgets/                       # 通用组件
+│       ├── adaptive_page_interface.dart # 自适应页面接口
+│       ├── adaptive_scaffold.dart       # 自适应布局组件
+│       ├── error_widget.dart           # 错误组件
+│       ├── loading_indicator.dart      # 加载指示器
+│       ├── product_card.dart           # 产品卡片
+│       └── skeleton_loader.dart        # 骨架屏
+```
+
+## 已使用的依赖库
+
+### 核心库
+
+| 库名 | 版本 | 用途 | 使用位置 |
+|------|------|------|----------|
+| `cupertino_icons` | ^1.0.8 | iOS 风格图标 | 全局使用 |
+| `flutter_localizations` | SDK | 国际化支持 | main.dart, app_localizations.dart |
+| `intl` | ^0.20.2 | 国际化工具 | l10n 文件, date_utils.dart |
+| `get` | git | 状态管理、路由管理、依赖注入 | ThemeService, AnimationService, main.dart 等 |
+
+### 网络与存储
+
+| 库名 | 版本 | 用途 | 使用位置 |
+|------|------|------|----------|
+| `dio` | ^5.9.2 | 网络请求 | ApiService |
+| `dio_cache_interceptor` | ^3.5.0 | Dio 网络请求缓存 | ApiService |
+| `shared_preferences` | git | 本地键值存储 | StorageService, ThemeService, AnimationService |
+| `connectivity_plus` | git | 网络状态检测 | ApiService, NetworkUtils |
+| `path_provider` | git | 文件路径获取 | LoggerService |
+
+### 平台与工具
+
+| 库名 | 版本 | 用途 | 使用位置 |
+|------|------|------|----------|
+| `flutter_local_notifications` | git | 本地通知 | NotificationService |
+| `package_info_plus` | git | 应用信息 | AppInfoService |
+| `fluttertoast` | git | Toast 消息提示 | ToastService |
+| `share_plus` | git | 分享功能 | CommonUtils |
+| `permission_handler` | git | 权限管理 | PermissionService |
+| `device_info_plus` | git | 设备信息 | 待开发 |
+| `logger` | ^2.7.0 | 日志管理 | LoggerService |
+| `pretty_dio_logger` | ^1.4.0 | Dio 日志美化 | ApiService |
+
+### UI 与动画
+
+| 库名 | 版本 | 用途 | 使用位置 |
+|------|------|------|----------|
+| `flutter_adaptive_scaffold` | git | 自适应布局 | AdaptivePageInterface, AdaptiveScaffold |
+| `animations` | git | 页面过渡动画 | AnimationService |
+| `flutter_screenutil` | 本地 v5.9.3 | 屏幕适配 | 全局使用（支持鸿蒙） |
+
+## 尚未使用的依赖库
+
+| 库名 | 版本 | 用途 | 建议使用场景 |
+|------|------|------|--------------|
+| `pigeon` | git | Flutter 与原生平台通信 | 需要调用原生 API 时使用 |
+| `orientation` | git | 屏幕方向控制 | 已改用 Flutter 原生 SystemChrome |
+| `platform_info` | ^5.0.0 | 平台识别 | 已改用 dart:io 的 Platform |
+
+## 建议添加的基础库
+
+| 库名 | 用途 | 优先级 |
+|------|------|--------|
+| `image_picker` | 图片选择、拍照 | 高 |
+| `url_launcher` | 打开 URL、拨打电话 | 高 |
+| `path_provider` | 文件路径获取 | 中 |
+| `camera` | 相机访问 | 中 |
+| `geolocator` | 地理定位 | 中 |
+| `fl_chart` | 图表库 | 低 |
+| `sqflite` | SQLite 数据库 | 低 |
+
+## 核心服务说明
+
+### 1. ApiService（网络请求服务）
+
+**功能：**
+- 基于 Dio 封装的网络请求
+- 支持缓存拦截器
+- 网络状态检测
+- 统一错误处理
+
+**使用示例：**
+```dart
+final api = AppService.instance.api;
+final response = await api.get('/products');
+```
+
+### 2. StorageService（本地存储服务）
+
+**功能：**
+- 基于 shared_preferences 封装
+- 支持键值对存储
+- 支持对象序列化
+
+**使用示例：**
+```dart
+final storage = AppService.instance.storage;
+await storage.setString('key', 'value');
+final value = storage.getString('key');
+```
+
+### 3. ThemeService（主题管理服务）
+
+**功能：**
+- 动态切换白天/夜间模式
+- 自定义主题色、次要色
+- 字体大小调节
+- 动画强度调节
+- 状态栏沉浸设置
+- 主题持久化存储
+
+**使用示例：**
+```dart
+final theme = AppService.instance.theme;
+await theme.toggleThemeMode();
+await theme.setPrimaryColor(Colors.blue);
+```
+
+### 4. OrientationService（屏幕方向服务）
+
+**功能：**
+- 锁定屏幕方向
+- 解锁屏幕方向
+- 获取当前屏幕方向
+
+**使用示例：**
+```dart
+final orientation = AppService.instance.orientation;
+await orientation.lockPortrait();
+await orientation.unlockOrientation();
+```
+
+### 5. NotificationService（通知服务）
+
+**功能：**
+- 本地通知管理
+- 定时通知
+- 进度通知
+- 大文本通知
+- 图片通知
+- 通知权限请求
+
+**使用示例：**
+```dart
+final notification = AppService.instance.notification;
+
+// 请求权限
+await notification.requestPermission();
+
+// 显示普通通知
+await notification.showNotification(
+  id: 1,
+  title: '标题',
+  body: '内容',
+);
+
+// 显示定时通知
+await notification.scheduleNotification(
+  id: 2,
+  title: '提醒',
+  body: '该吃饭了！',
+  scheduledDate: DateTime.now().add(Duration(hours: 1)),
+);
+
+// 取消通知
+await notification.cancelNotification(1);
+```
+
+### 6. AppInfoService（应用信息服务）
+
+**功能：**
+- 获取应用名称
+- 获取包名
+- 获取版本号
+- 获取构建号
+- 版本比较
+- 更新检测
+
+**使用示例：**
+```dart
+final appInfo = AppService.instance.appInfo;
+
+// 获取版本信息
+print('版本: ${appInfo.version}');
+print('构建号: ${appInfo.buildNumber}');
+print('完整版本: ${appInfo.fullVersion}');
+
+// 检查是否需要更新
+if (appInfo.needsUpdate('2.0.0')) {
+  print('需要更新应用');
+}
+
+// 获取应用信息摘要
+print(appInfo.appInfoString);
+```
+
+### 7. ToastService（消息提示服务）
+
+**功能：**
+- 4 种消息类型：信息、成功（积极）、警告、错误（消极）
+- 4 种显示样式：GetX、FlutterToast、默认、混合
+- 样式动态切换
+- 支持自定义显示时长
+
+**消息类型：**
+- `MessageType.info` - 普通信息（蓝色）
+- `MessageType.success` - 成功/积极消息（绿色）
+- `MessageType.warning` - 警告消息（橙色）
+- `MessageType.error` - 错误/消极消息（红色）
+
+**显示样式：**
+- `ToastStyle.getx` - GetX 默认样式
+- `ToastStyle.fluttertoast` - FlutterToast 样式
+- `ToastStyle.default_` - 默认样式（Cupertino 风格）
+- `ToastStyle.hybrid` - 混合样式（推荐）
+
+**使用示例：**
+```dart
+final toast = AppService.instance.toast;
+
+// 设置显示样式
+toast.setStyle(ToastStyle.hybrid);
+
+// 显示信息消息
+await toast.info('这是一条信息');
+
+// 显示成功消息（积极）
+await toast.success('操作成功！');
+
+// 显示警告消息
+await toast.warning('请注意！');
+
+// 显示错误消息（消极）
+await toast.error('操作失败！');
+
+// 自定义显示
+await toast.show(
+  '自定义消息',
+  type: MessageType.info,
+  style: ToastStyle.getx,
+  duration: Duration(seconds: 3),
+);
+
+// 取消所有消息
+toast.cancelAll();
+```
+
+### 8. PermissionService（权限管理服务）
+
+**功能：**
+- 支持 15 种常见权限类型（相机、麦克风、相册、位置等）
+- 跨平台权限适配（iOS、Android、HarmonyOS、Web、Windows、macOS、Linux）
+- 权限状态记录和查询功能
+- 批量权限检查和请求功能
+
+**使用示例：**
+```dart
+final permission = AppService.instance.permission;
+
+// 检查单个权限
+final status = await permission.checkPermission(PermissionType.camera);
+if (status.isGranted) {
+  // 权限已授予
+}
+
+// 请求单个权限
+final result = await permission.requestPermission(PermissionType.camera);
+if (result.isGranted) {
+  // 权限已授予
+}
+
+// 批量检查权限
+final permissions = [
+  PermissionType.camera,
+  PermissionType.microphone,
+  PermissionType.photos,
+];
+final statuses = await permission.checkPermissions(permissions);
+
+// 批量请求权限
+final results = await permission.requestPermissions(permissions);
+
+// 获取所有权限状态
+final allStatuses = permission.getAllPermissionStatuses();
+```
+
+### 9. AnimationService（动画管理服务）
+
+**功能：**
+- 使用 `animations` 库实现专业动画效果
+- 支持动画开关、速度、强度、曲线四种参数调节
+- 提供 7 种预设模式（Standard、Fast、Slow、Smooth、Bouncy、Minimal、None）
+- 支持 9 种动画曲线类型
+- 配置持久化存储，应用重启后保持设置
+
+**预设模式：**
+- `AnimationPreset.standard` - 标准动画（默认）
+- `AnimationPreset.fast` - 快速动画
+- `AnimationPreset.slow` - 慢速动画
+- `AnimationPreset.smooth` - 平滑动画
+- `AnimationPreset.bouncy` - 弹性动画
+- `AnimationPreset.minimal` - 最小动画
+- `AnimationPreset.none` - 无动画
+
+**使用示例：**
+```dart
+final animation = AppService.instance.animation;
+
+// 获取动画配置
+print('动画已启用: ${animation.enabled}');
+print('动画速度: ${animation.speed}');
+print('动画强度: ${animation.intensity}');
+print('动画曲线: ${animation.curveType}');
+
+// 设置动画参数
+await animation.setEnabled(true);
+await animation.setSpeed(1.5);
+await animation.setIntensity(1.2);
+await animation.setCurveType(AnimationCurveType.easeInOut);
+await animation.setPreset(AnimationPreset.smooth);
+
+// 使用动画组件
+AnimatedButton(
+  onPressed: () => print('点击'),
+  child: Text('动画按钮'),
+);
+
+AnimatedCard(
+  onTap: () => print('点击卡片'),
+  child: Text('动画卡片'),
+);
+
+// 页面转场动画
+PageTransitions.fadeThrough(
+  child: NewPage(),
+);
+```
+
+### 10. LoggerService（日志管理服务）
+
+**功能：**
+- 支持日志开关、级别、文件写入配置
+- 支持 5 种日志级别（Debug、Info、Warning、Error、Off）
+- 支持控制台输出和文件输出
+- 支持日志文件自动清理（按大小和数量）
+- 配置持久化存储
+
+**使用示例：**
+```dart
+// 使用 AppLogger 全局工具类
+AppLogger.d('调试信息');
+AppLogger.i('普通信息');
+AppLogger.w('警告信息');
+AppLogger.e('错误信息');
+
+// 或使用 LoggerService
+final logger = AppService.instance.logger;
+logger.debug('调试信息');
+logger.info('普通信息');
+logger.warning('警告信息');
+logger.error('错误信息');
+
+// 配置日志
+await AppLogger.setEnabled(true);
+await AppLogger.setWriteToFile(true);
+
+// 获取日志文件
+final files = await AppLogger.getLogFiles();
+final content = await AppLogger.getLogContent();
+
+// 清空日志
+await AppLogger.clearLogs();
+```
+
+### 11. ScreenUtilConfig（屏幕适配配置）
+
+**功能：**
+- 设计稿尺寸配置（默认 375x812）
+- 最小字体适配开关
+- 分屏模式开关
+- 缩放开关控制
+- 配置持久化存储
+
+**使用示例：**
+```dart
+// 初始化
+final screenUtil = AppService.instance.screenUtil;
+screenUtil.initScreenUtil(context);
+
+// 或异步初始化
+await screenUtil.ensureScreenSizeAndInit(context);
+
+// 配置设计稿尺寸
+await screenUtil.setDesignSize(Size(375, 812));
+await screenUtil.setDesignWidth(375);
+await screenUtil.setDesignHeight(812);
+
+// 配置适配选项
+await screenUtil.setMinTextAdapt(true);
+await screenUtil.setSplitScreenMode(true);
+await screenUtil.setScaleEnabled(true);
+
+// 使用扩展方法
+Container(
+  width: 100.w,      // 按设计稿比例缩放
+  height: 50.h,
+  padding: EdgeInsets.all(16.w),
+  child: Text(
+    'Hello',
+    style: TextStyle(fontSize: 14.sp),  // 字体缩放
+  ),
+)
+
+// 禁用缩放时，扩展方法返回原始值
+await screenUtil.setScaleEnabled(false);
+// 此时 100.w 返回 100.0
+```
+
+## 页面规范系统
+
+> 📖 详细文档请查看 [PAGE_STANDARDS.md](./PAGE_STANDARDS.md)
+
+页面规范系统提供统一的页面构建标准，确保所有页面遵循统一的开发规范。
+
+### 核心组件
+
+| 组件 | 说明 |
+|------|------|
+| `PageStandards` | 页面规范配置类 |
+| `PageStandardsMixin` | 页面混入，自动注入规范 |
+| `StandardPage` | 标准页面基类 |
+| `PageValidator` | 页面验证器 |
+| `PageRegistry` | 页面注册表 |
+
+### 快速使用
+
+```dart
+class MyPage extends StandardPage {
+  const MyPage({super.key});
+  
+  @override
+  State<MyPage> createState() => _MyPageState();
+}
+
+class _MyPageState extends StandardPageState<MyPage> {
+  @override
+  Widget buildPage(BuildContext context) {
+    return CupertinoPageScaffold(
+      backgroundColor: backgroundColor,  // 自动获取主题背景色
+      child: Text(
+        l10n.appTitle,  // 自动获取多语言
+        style: textStyle,  // 自动获取主题文字样式
+      ),
+    );
+  }
+}
+```
+
+---
+
+## 主题系统说明
+
+> 📖 页面主题使用详见 [PAGE_STANDARDS.md](./PAGE_STANDARDS.md#页面规范系统)
+
+### 主题属性
+
+创建新页面时，**必须读取所有主题值**：
+
+```dart
+@override
+Widget build(BuildContext context) {
+  final theme = AppService.instance.theme;
+  
+  final isDarkMode = theme.isDarkMode;
+  final primaryColor = theme.primaryColor;
+  final secondaryColor = theme.secondaryColor;
+  final fontSize = theme.fontSize;
+  final textColor = theme.textColor;
+  final backgroundColor = theme.backgroundColor;
+  
+  return CupertinoPageScaffold(
+    backgroundColor: backgroundColor,
+    child: Text('Hello', style: TextStyle(color: textColor)),
+  );
+}
+```
+
+### 主题属性说明
+
+| 属性 | 类型 | 说明 | 默认值 |
+|------|------|------|--------|
+| `isDarkMode` | bool | 是否为深色模式 | false |
+| `primaryColor` | Color | 主题色 | Colors.blue |
+| `secondaryColor` | Color | 次要色 | Colors.orange |
+| `fontSize` | double | 基础字体大小 | 16.0 |
+| `textColor` | Color | 文字颜色 | Colors.black |
+| `backgroundColor` | Color | 背景颜色 | Colors.white |
+
+---
+
+## 国际化说明
+
+### 支持的语言
+
+- 英文（en）
+- 中文（zh）
+- 繁体中文（zh_Hant）
+
+### 使用方法
+
+```dart
+final l10n = AppLocalizations.of(context)!;
+Text(l10n.appTitle)
+```
+
+### 添加新的翻译
+
+1. 编辑 `lib/src/l10n/app_en.arb` 和 `lib/src/l10n/app_zh.arb`
+2. 运行 `flutter gen-l10n` 生成代码
+
+## 注意事项
+
+### 1. 组件风格
+
+- **优先使用 iOS 风格组件**（Cupertino）
+- 若 iOS 无对应组件，再使用 Material 组件
+- 示例：使用 `CupertinoButton` 而非 `ElevatedButton`
+
+### 2. 响应式布局
+
+- 使用 `LayoutBuilder` 和 `MediaQuery` 实现响应式
+- 支持横竖屏切换
+- 适配不同屏幕尺寸
+
+### 3. 骨架屏与动画
+
+- 页面加载时显示骨架屏
+- 使用 `AnimationService` 统一管理动画
+- 动画参数可在设置中调节（开关、速度、强度、曲线）
+- 使用 `AnimatedButton`、`AnimatedCard` 等动画组件
+
+### 4. 网络图片加载
+
+- 使用 `Image.network` 加载网络图片
+- 添加 `loadingBuilder` 和 `errorBuilder`
+- 示例：
+```dart
+Image.network(
+  url,
+  loadingBuilder: (context, child, loadingProgress) {
+    if (loadingProgress == null) return child;
+    return const CupertinoActivityIndicator();
+  },
+  errorBuilder: (context, error, stackTrace) {
+    return const Icon(CupertinoIcons.exclamationmark_circle);
+  },
+)
+```
+
+### 5. 平台识别
+
+使用 `PlatformUtils` 识别平台：
+
+```dart
+final platform = PlatformUtils();
+if (platform.isIOS) {
+  // iOS 特定逻辑
+} else if (platform.isAndroid) {
+  // Android 特定逻辑
+} else if (platform.isHarmonyOS) {
+  // 鸿蒙特定逻辑
+}
+```
+
+### 6. 状态管理
+
+使用 GetX 进行状态管理：
+
+```dart
+// 定义响应式变量
+final count = 0.obs;
+
+// 更新值
+count.value++;
+
+// 监听变化
+Obx(() => Text('${count.value}'))
+```
+
+### 7. 路由管理
+
+使用 GetX 进行路由管理：
+
+```dart
+// 跳转到新页面
+Get.to(const NewPage());
+
+// 返回上一页
+Get.back();
+
+// 替换当前页面
+Get.off(const NewPage());
+
+// 清空栈并跳转
+Get.offAll(const HomePage());
+```
+
+### 8. 依赖注入
+
+使用 GetX 进行依赖注入：
+
+```dart
+// 注册服务
+Get.put(ThemeService());
+
+// 获取服务
+final theme = Get.find<ThemeService>();
+```
+
+## 开发规范
+
+### 1. 文件命名
+
+- 文件名使用小写下划线：`theme_service.dart`
+- 类名使用大驼峰：`ThemeService`
+
+### 2. 导入顺序
+
+```dart
+// 1. Flutter SDK
+import 'package:flutter/material.dart';
+import 'package:flutter/cupertino.dart';
+
+// 2. 第三方库
+import 'package:get/get.dart';
+
+// 3. 项目内部文件
+import 'package:mom_kitchen/src/services/app_service.dart';
+```
+
+### 3. 注释规范
+
+- 使用中文注释
+- 公共方法必须添加注释说明
+- 复杂逻辑添加行内注释
+
+### 4. 代码风格
+
+- 使用 `const` 构造函数
+- 使用 `final` 定义不可变变量
+- 避免使用 `dynamic`，明确类型
+
+## 常见问题
+
+### Q1: 如何添加新的主题属性？
+
+1. 在 `ThemeService` 中添加新的响应式变量
+2. 在 `_loadTheme()` 和 `_saveTheme()` 中添加加载和保存逻辑
+3. 添加 getter 方法
+4. 在 `getThemeData()` 中应用新属性
+5. 更新本文档的主题属性表格
+
+### Q2: 如何添加新的语言支持？
+
+1. 在 `l10n.yaml` 中添加新的语言代码
+2. 创建对应的 ARB 文件：`app_xx.arb`
+3. 运行 `flutter gen-l10n` 生成代码
+
+### Q3: 如何使用未使用的库？
+
+参考本文档"尚未使用的依赖库"表格中的建议使用场景，在相应的服务或页面中集成。
+
+### Q4: 如何创建新页面？
+
+请参考 [PAGE_STANDARDS.md](./PAGE_STANDARDS.md#最佳实践) 中的最佳实践部分。
+
+---
+
+## 相关文档
+
+| 文档 | 说明 |
+|------|------|
+| [PAGE_STANDARDS.md](./PAGE_STANDARDS.md) | 页面规范与验证系统详细说明 |
+| [CHANGELOG.md](../../CHANGELOG.md) | 项目更新日志 |
+
+---
+
+**最后更新时间：** 2026-04-08
+**维护者：** Mom's Kitchen 开发团队