Files

Developer 8c41df955c api 升级v2.0

2026-04-10 06:41:08 +08:00

16 KiB

Raw Blame History

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       # 日志管理服务
│   │   ├── 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

平台与工具

库名	版本	用途	使用位置

UI 与动画

库名	版本	用途	使用位置
`flutter_adaptive_scaffold`	git	自适应布局	AdaptivePageInterface, AdaptiveScaffold
`animations`	git	页面过渡动画	AnimationService
`flutter_screenutil`	本地 v5.9.3	屏幕适配	全局使用（支持鸿蒙）

核心服务说明

1. ApiService（网络请求服务）

功能：

基于 Dio 封装的网络请求
支持缓存拦截器
网络状态检测
统一错误处理

使用示例：

final api = AppService.instance.api;
final response = await api.get('/products');

2. StorageService（本地存储服务）

功能：

基于 shared_preferences 封装
支持键值对存储
支持对象序列化

使用示例：

final storage = AppService.instance.storage;
await storage.setString('key', 'value');
final value = storage.getString('key');

3. ThemeService（主题管理服务）

功能：

动态切换白天/夜间模式
自定义主题色、次要色
字体大小调节
动画强度调节
状态栏沉浸设置
主题持久化存储

使用示例：

final theme = AppService.instance.theme;
await theme.toggleThemeMode();
await theme.setPrimaryColor(Colors.blue);

4. OrientationService（屏幕方向服务）

功能：

锁定屏幕方向
解锁屏幕方向
获取当前屏幕方向

使用示例：

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 - 无动画

使用示例：

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）
支持控制台输出和文件输出
支持日志文件自动清理（按大小和数量）
配置持久化存储

使用示例：

// 使用 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）
最小字体适配开关
分屏模式开关
缩放开关控制
配置持久化存储

使用示例：

// 初始化
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

页面规范系统提供统一的页面构建标准，确保所有页面遵循统一的开发规范。

核心组件

组件	说明
`PageStandards`	页面规范配置类
`PageStandardsMixin`	页面混入，自动注入规范
`StandardPage`	标准页面基类
`PageValidator`	页面验证器
`PageRegistry`	页面注册表

快速使用

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

主题属性

创建新页面时，必须读取所有主题值：

@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）

使用方法

final l10n = AppLocalizations.of(context)!;
Text(l10n.appTitle)

添加新的翻译

编辑 lib/src/l10n/app_en.arb 和 lib/src/l10n/app_zh.arb
运行 flutter gen-l10n 生成代码

注意事项

1. 组件风格

优先使用 iOS 风格组件（Cupertino）
若 iOS 无对应组件，再使用 Material 组件
示例：使用 CupertinoButton 而非 ElevatedButton

2. 响应式布局

使用 LayoutBuilder 和 MediaQuery 实现响应式
支持横竖屏切换
适配不同屏幕尺寸

3. 骨架屏与动画

页面加载时显示骨架屏
使用 AnimationService 统一管理动画
动画参数可在设置中调节（开关、速度、强度、曲线）
使用 AnimatedButton、AnimatedCard 等动画组件

4. 网络图片加载

使用 Image.network 加载网络图片
添加 loadingBuilder 和 errorBuilder
示例：

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 识别平台：

final platform = PlatformUtils();
if (platform.isIOS) {
  // iOS 特定逻辑
} else if (platform.isAndroid) {
  // Android 特定逻辑
} else if (platform.isHarmonyOS) {
  // 鸿蒙特定逻辑
}

6. 状态管理

使用 GetX 进行状态管理：

// 定义响应式变量
final count = 0.obs;

// 更新值
count.value++;

// 监听变化
Obx(() => Text('${count.value}'))

开发规范

1. 文件命名

文件名使用小写下划线：theme_service.dart
类名使用大驼峰：ThemeService

2. 导入顺序

// 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: 如何添加新的主题属性？

在 ThemeService 中添加新的响应式变量
在 _loadTheme() 和 _saveTheme() 中添加加载和保存逻辑
添加 getter 方法
在 getThemeData() 中应用新属性
更新本文档的主题属性表格

Q2: 如何添加新的语言支持？

在 l10n.yaml 中添加新的语言代码
创建对应的 ARB 文件：app_xx.arb
运行 flutter gen-l10n 生成代码

Q3: 如何使用未使用的库？

参考本文档"尚未使用的依赖库"表格中的建议使用场景，在相应的服务或页面中集成。

Q4: 如何创建新页面？

请参考 PAGE_STANDARDS.md 中的最佳实践部分。

文档	说明
PAGE_STANDARDS.md	页面规范与验证系统详细说明
CHANGELOG.md	项目更新日志

16 KiB Raw Blame History Unescape Escape

Mom's Kitchen 项目基础支撑库说明

项目架构

已使用的依赖库

核心库

网络与存储

平台与工具

UI 与动画

核心服务说明

1. ApiService（网络请求服务）

2. StorageService（本地存储服务）

3. ThemeService（主题管理服务）

4. OrientationService（屏幕方向服务）

7. ToastService（消息提示服务）

9. AnimationService（动画管理服务）

10. LoggerService（日志管理服务）

11. ScreenUtilConfig（屏幕适配配置）

页面规范系统

核心组件

快速使用

主题系统说明

主题属性

主题属性说明

国际化说明

支持的语言

使用方法

添加新的翻译

注意事项

1. 组件风格

2. 响应式布局

3. 骨架屏与动画

4. 网络图片加载

5. 平台识别

6. 状态管理

开发规范

1. 文件命名

2. 导入顺序

3. 注释规范

4. 代码风格

常见问题

Q1: 如何添加新的主题属性？

Q2: 如何添加新的语言支持？

Q3: 如何使用未使用的库？

Q4: 如何创建新页面？

相关文档

16 KiB

Raw Blame History