562 lines
16 KiB
Markdown
562 lines
16 KiB
Markdown
# 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 | 屏幕适配 | 全局使用（支持鸿蒙） |
|
||
|
||
|
||
|
||
## 核心服务说明
|
||
|
||
### 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();
|
||
```
|
||
|
||
|
||
|
||
### 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` - 混合样式（推荐）
|
||
|
||
|
||
### 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}'))
|
||
```
|
||
|
||
|
||
## 开发规范
|
||
|
||
### 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 开发团队
|