kitchen/个性化设置快速参考.md

🎯 个性化设置 - 快速参考卡

📍 页面导航

主标签页底部导航
    ↓
  [个人] 标签
    ↓
个人中心页面
    ↓
设置区域
    ├─ 个性化设置 ← NEW! 点击进入
    └─ 主题设置
    └─ 退出登录

📁 项目文件结构

lib/src/
├── controllers/
│   ├── personalization_controller.dart ← NEW!
│   ├── profile_controller.dart (已修改)
│   └── ...
├── pages/
│   ├── personalization_page.dart ← NEW!
│   ├── profile_page.dart (已修改)
│   └── ...
└── routes/
    └── app_routes.dart (已修改)

🎮 功能快速入门

// 1️⃣ 获取控制器
final controller = Get.find<PersonalizationController>();

// 2️⃣ 设置主题颜色
await controller.setThemeColor(Color(0xFF2196F3));

// 3️⃣ 调整字体大小
await controller.setFontSize(18.0);

// 4️⃣ 切换深色模式
await controller.toggleDarkMode();

// 5️⃣ 设置动画强度
await controller.setAnimationIntensity(1.5);

// 6️⃣ 切换语言
await controller.setLanguage('zh_Hant');

// 7️⃣ 恢复默认值
await controller.resetToDefaults();

📋 功能列表

#	功能	默认值	范围/选项
1	主题颜色	蓝色 (#2196F3)	5种预设 + 自定义
2	字体大小	16pt	12-24pt
3	深色模式	关闭	开启/关闭
4	动画强度	1.0x	0.0-2.0x
5	语言	简体中文	中/繁/英
6	恢复默认	-	一键重置

🎨 颜色预设值

Color colors = {
  '蓝色':  Color(0xFF2196F3),
  '橙色':  Color(0xFFFF9800),
  '蓝紫':  Color(0xFF9C27B0),
  '草绿':  Color(0xFF4CAF50),
  '深红':  Color(0xFFF44336),
};

📝 类定义速览

PersonalizationController

class PersonalizationController extends BaseController {
  // 预设列表
  RxList<String> themePresets;
  RxList<Color> themePresetColors;
  RxList<String> animationPresets;
  RxList<String> languageNames;
  RxList<String> languageCodes;

  // 业务方法
  Future<void> setThemeColor(Color color);
  Future<void> setFontSize(double size);
  Future<void> toggleDarkMode();
  Future<void> setAnimationIntensity(double intensity);
  Future<void> setAnimationPreset(AnimationPreset preset);
  Future<void> setLanguage(String languageCode);
  Future<void> resetToDefaults();

  // 计算属性
  String get currentThemeColorName;
  double get currentFontSize;
  bool get isDarkMode;
  double get currentAnimationIntensity;
  String get currentLanguage;
}

PersonalizationPage

class PersonalizationPage extends StatelessWidget {
  const PersonalizationPage({super.key});

  // 5个主要UI部分
  Widget _buildColorPicker(...);           // 颜色选择
  Widget _buildFontSizeSlider(...);        // 字体大小
  Widget _buildDarkModeToggle(...);        // 深色模式
  Widget _buildAnimationSettings(...);     // 动画效果
  Widget _buildLanguageSelector(...);      // 语言选择
}

🔌 集成点总结

路由注册 (app_routes.dart)

// ✅ 已添加
static const String personalization = '/personalization';

GetPage(
  name: personalization,
  page: () => const PersonalizationPage(),
  middlewares: [PageStandardsMiddleware()],
),

控制器绑定 (app_binding.dart)

// ✅ 已添加
Get.lazyPut(() => PersonalizationController(), fenix: true);

导航菜单 (profile_page.dart)

// ✅ 已添加 - 在设置区域第一项
CupertinoListTile(
  title: Text('个性化设置'),
  trailing: Icon(CupertinoIcons.chevron_right),
  onTap: () => Get.to(() => const PersonalizationPage()),
),

💾 数据持久化键值

SharedPreferences keys:
- is_dark_mode
- primary_color
- secondary_color
- font_size
- animation_intensity
- text_color
- background_color
- locale
- dialog_style
- toast_style

🚀 快速开发建议

添加新的设置项

// 1. 在 PersonalizationController 添加属性
final Rx<NewType> newSetting = defaultValue.obs;

// 2. 在 ThemeService 添加保存方法
Future<void> saveNewSetting(NewType value) async {
  await _prefs.set...(key, value);
}

// 3. 在 PersonalizationController 添加方法
Future<void> setNewSetting(NewType value) async {
  await _themeService.saveNewSetting(value);
}

// 4. 在 PersonalizationPage 添加 UI 控件
Widget _buildNewSetting(...) { ... }

// 5. 在 build 方法中追加
_buildNewSetting(...)

修改预设值

// 颜色预设 - PersonalizationController
themePresets.add('新颜色');
themePresetColors.add(Color(0xFF...));

// 语言预设 - PersonalizationController
languageNames.add('新语言');
languageCodes.add('new');

📊 状态流转图

初始化
  ↓
加载保存的设置 (SharedPreferences)
  ↓
[个性化设置] 页面显示
  ↓
用户交互 (点击/滑动/切换)
  ↓
Controller 更新状态
  ↓
ThemeService 保存设置
  ↓
全局 UI 响应更新
  ↓
Snackbar 提示成功

⚠️ 常见坑

❌ 不要直接修改 _themeService 的值

// ❌ 错误
_themeService.primaryColor.value = color;

// ✅ 正确
await _themeService.setPrimaryColor(color);

❌ 不要忘记 await

// ❌ 错误 - 设置可能不保存
controller.setThemeColor(color);

// ✅ 正确
await controller.setThemeColor(color);

❌ 不要在 StatelessWidget 中使用 setState

// ❌ 错误
setState(() { ... });

// ✅ 正确
Obx(() => ...);  // 使用 GetX 响应式

🧪 快速测试

测试主题颜色

// 在任意页面测试
Get.find<PersonalizationController>()
  .setThemeColor(Color(0xFFFF9800));
// 观察整个应用颜色变化

测试语言切换

Get.find<PersonalizationController>()
  .setLanguage('en');
// 观察界面文本变化

测试数据持久化

// 1. 设置值
await controller.setFontSize(20.0);
// 2. 重启应用
// 3. 验证字体仍为 20.0

📞 问题排查

症状	可能原因	解决方案
页面不显示	路由未注册	检查 app_routes.dart
控制器为 null	未在 binding 中注册	检查 app_binding.dart
设置不保存	SharedPreferences 权限问题	检查 pubspec.yaml 依赖
UI 不更新	缺少 Obx 或 GetBuilder	用 Obx() 包裹可观察值
语言不切换	本地化资源未加载	检查 l10n 配置

---

快速查询表 | 更新时间: 2026-04-08 保存此文件以便快速参考! 📌