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 (已修改)
```

## 🎮 功能快速入门

```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 | 恢复默认 | - | 一键重置 |

## 🎨 颜色预设值

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

## 📝 类定义速览

### PersonalizationController

```dart
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

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

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

## 🔌 集成点总结

### 路由注册 (app_routes.dart)
```dart
// ✅ 已添加
static const String personalization = '/personalization';

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

### 控制器绑定 (app_binding.dart)
```dart
// ✅ 已添加
Get.lazyPut(() => PersonalizationController(), fenix: true);
```

### 导航菜单 (profile_page.dart)
```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
```

## 🚀 快速开发建议

### 添加新的设置项
```dart
// 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(...)
```

### 修改预设值
```dart
// 颜色预设 - PersonalizationController
themePresets.add('新颜色');
themePresetColors.add(Color(0xFF...));

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

## 📊 状态流转图

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

## ⚠️ 常见坑

❌ 不要直接修改 `_themeService` 的值
```dart
// ❌ 错误
_themeService.primaryColor.value = color;

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

❌ 不要忘记 `await`
```dart
// ❌ 错误 - 设置可能不保存
controller.setThemeColor(color);

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

❌ 不要在 StatelessWidget 中使用 `setState`
```dart
// ❌ 错误
setState(() { ... });

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

## 🧪 快速测试

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

### 测试语言切换
```dart
Get.find<PersonalizationController>()
  .setLanguage('en');
// 观察界面文本变化
```

### 测试数据持久化
```dart
// 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
保存此文件以便快速参考! 📌