kitchen/lib

Cute 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

平台与工具

库名	版本	用途	使用位置

| 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 封装的网络请求
• 支持缓存拦截器
• 网络状态检测
• 统一错误处理

使用示例：

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)

添加新的翻译

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
• 示例：

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:cute_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	页面规范与验证系统详细说明
CHANGELOG.md	项目更新日志

---

最后更新时间： 2026-04-08 维护者： Cute Kitchen 开发团队