# 📚 PersonalizationController API 参考文档

## 类定义

```dart
class PersonalizationController extends BaseController {
  // 这是管理所有个性化设置的核心控制器
  // 继承自 BaseController 获得加载状态管理
  // 与 ThemeService 和 AnimationService 协作
}
```

---

## 🎨 属性 (Properties)

### 颜色相关

#### `themePresets` - 主题颜色名称列表
```dart
final RxList<String> themePresets = RxList([
  '蓝色',
  '橙色',
  '蓝紫',
  '草绿',
  '深红',
]);

// 访问方式
List<String> colors = controller.themePresets;
```

#### `themePresetColors` - 主题颜色值列表
```dart
final RxList<Color> themePresetColors = RxList([
  Color(0xFF2196F3),  // 蓝色
  Color(0xFFFF9800),  // 橙色
  Color(0xFF9C27B0),  // 蓝紫
  Color(0xFF4CAF50),  // 草绿
  Color(0xFFF44336),  // 深红
]);

// 访问方式
List<Color> colors = controller.themePresetColors;
Color firstColor = controller.themePresetColors[0];
```

### 动画相关

#### `animationPresets` - 动画预设名称列表
```dart
final RxList<String> animationPresets = RxList([
  '禁用',
  '低速',
  '标准',
  '高速',
]);
```

#### `animationPresetValues` - 动画预设枚举值列表
```dart
final RxList<AnimationPreset> animationPresetValues = RxList([
  AnimationPreset.none,      // 禁用
  AnimationPreset.slow,      // 低速
  AnimationPreset.standard,  // 标准
  AnimationPreset.fast,      // 高速
]);
```

### 语言相关

#### `languageNames` - 语言显示名称列表
```dart
final RxList<String> languageNames = RxList([
  '简体中文',
  '繁体中文',
  'English',
]);

// 用来显示给用户的语言名称
```

#### `languageCodes` - 语言代码列表
```dart
final RxList<String> languageCodes = RxList([
  'zh',       // 简体中文
  'zh_Hant',  // 繁体中文
  'en',       // English
]);

// 对应的语言代码，用于切换
```

---

## 🎯 方法 (Methods)

### 设置主题颜色

#### `setThemeColor(Color color)`
设置应用的主题颜色，颜色变化会立即应用到整个应用

**参数:**
- `color` `Color` - 要应用的颜色值

**返回:**
- `Future<void>` - 异步操作，等待保存完成

**示例:**
```dart
// 设置为蓝色
await controller.setThemeColor(Color(0xFF2196F3));

// 设置为自定义颜色
await controller.setThemeColor(Color(0xFF123456));

// 在 UI 中使用
ElevatedButton(
  onPressed: () async {
    await controller.setThemeColor(Colors.blue);
    Get.snackbar('成功', '主题颜色已更改');
  },
  child: Text('切换蓝色主题'),
)
```

**关联方法:**
- 触发：`ThemeService.setPrimaryColor(color)`
- 保存：`SharedPreferences.setInt('primary_color', color.value)`

---

### 调整字体大小

#### `setFontSize(double size)`
调整应用中所有文本的字体大小

**参数:**
- `size` `double` - 字体大小，单位为磅 (pt)
  - 最小值：12.0
  - 最大值：24.0
  - 推荐范围：14.0 - 18.0

**返回:**
- `Future<void>` - 异步操作

**示例:**
```dart
// 设置为18点
await controller.setFontSize(18.0);

// 增加2点
double current = controller.currentFontSize;
await controller.setFontSize(current + 2.0);

// 在滑块中使用
CupertinoSlider(
  value: controller.currentFontSize,
  min: 12.0,
  max: 24.0,
  onChanged: (value) => controller.setFontSize(value),
)
```

**注意事项:**
- 字体大小会影响所有使用 `ThemeService.fontSize` 的文本
- 不会影响系统组件的字体

---

### 切换深色模式

#### `toggleDarkMode()`
切换应用深色模式（开启 ↔ 关闭）

**参数:**
- 无

**返回:**
- `Future<void>` - 异步操作

**示例:**
```dart
// 简单切换
await controller.toggleDarkMode();

// 在开关中使用
CupertinoSwitch(
  value: controller.isDarkMode,
  onChanged: (_) => controller.toggleDarkMode(),
)

// 获取当前状态
bool isDark = controller.isDarkMode;
```

**行为:**
- 启用深色模式：文本 → 白色，背景 → 黑色
- 禁用深色模式：文本 → 黑色，背景 → 白色
- 同时更新状态栏样式

---

### 设置动画强度

#### `setAnimationIntensity(double intensity)`
调整应用动画的强度倍数

**参数:**
- `intensity` `double` - 动画强度倍数
  - 范围：0.0 - 2.0
  - 0.0：禁用动画
  - 1.0：正常速度（默认）
  - 2.0：最快速度

**返回:**
- `Future<void>` - 异步操作

**示例:**
```dart
// 设置为快速（1.5倍）
await controller.setAnimationIntensity(1.5);

// 禁用所有动画
await controller.setAnimationIntensity(0.0);

// 在滑块中使用
CupertinoSlider(
  value: controller.currentAnimationIntensity,
  min: 0.0,
  max: 2.0,
  divisions: 10,
  onChanged: (value) => controller.setAnimationIntensity(value),
)
```

**影响范围:**
- 页面转换动画
- 控件切换动画
- 加载指示器动画

---

### 设置动画预设

#### `setAnimationPreset(AnimationPreset preset)`
设置预定义的动画配置

**参数:**
- `preset` `AnimationPreset` - 动画预设枚举值
  - `AnimationPreset.none` - 禁用
  - `AnimationPreset.slow` - 低速
  - `AnimationPreset.standard` - 标准
  - `AnimationPreset.fast` - 高速

**返回:**
- `Future<void>` - 异步操作

**示例:**
```dart
// 设置为高速
await controller.setAnimationPreset(AnimationPreset.fast);

// 禁用动画
await controller.setAnimationPreset(AnimationPreset.none);

// 在选择器中使用
for (int i = 0; i < controller.animationPresets.length; i++) {
  GestureDetector(
    onTap: () => controller.setAnimationPreset(
      controller.animationPresetValues[i],
    ),
    child: Text(controller.animationPresets[i]),
  );
}
```

**预设对比:**
| 预设 | 速度 | 强度 | 曲线 |
|------|------|------|------|
| none | - | - | - |
| slow | 0.5x | 1.2 | slowMiddle |
| standard | 1.0x | 1.0 | easeInOut |
| fast | 2.0x | 0.8 | fastOutSlowIn |

---

### 切换语言

#### `setLanguage(String languageCode)`
切换应用的显示语言（国际化）

**参数:**
- `languageCode` `String` - 语言代码
  - `'zh'` - 简体中文
  - `'zh_Hant'` - 繁体中文
  - `'en'` - English

**返回:**
- `Future<void>` - 异步操作

**示例:**
```dart
// 切换为英文
await controller.setLanguage('en');

// 切换为繁体中文
await controller.setLanguage('zh_Hant');

// 在语言选择器中使用
for (int i = 0; i < controller.languageCodes.length; i++) {
  GestureDetector(
    onTap: () => controller.setLanguage(controller.languageCodes[i]),
    child: Text(controller.languageNames[i]),
  );
}
```

**行为:**
- 调用 `Get.updateLocale(locale)` 更新本地化
- 界面中所有使用 `AppLocalizations` 的文本立即更新
- 新的语言设置已保存到存储

**支持的语言:**
- 中文（简体）- 默认
- 中文（繁体）
- 英文

---

### 恢复默认设置

#### `resetToDefaults()`
将所有设置恢复到应用默认值

**参数:**
- 无

**返回:**
- `Future<void>` - 异步操作

**示例:**
```dart
// 确认后恢复默认
showCupertinoDialog(
  context: context,
  builder: (context) => CupertinoAlertDialog(
    title: Text('恢复默认设置?'),
    content: Text('这将重置所有个性化设置'),
    actions: [
      CupertinoDialogAction(
        onPressed: () => Get.back(),
        child: Text('取消'),
      ),
      CupertinoDialogAction(
        isDestructiveAction: true,
        onPressed: () {
          Get.back();
          controller.resetToDefaults();
        },
        child: Text('确定'),
      ),
    ],
  ),
)
```

**恢复到的默认值:**
```dart
isDarkMode           → false
primaryColor         → Color(0xFF2196F3)  // 蓝色
secondaryColor       → Color(0xFFFF9800)  // 橙色
fontSize             → 16.0
isStatusBarImmersive → false
backgroundColor      → Color(0xFFFFFFFF)  // 白色
textColor            → Color(0xFF000000)  // 黑色
animationIntensity   → 1.0
currentLocale        → 'zh'               // 简体中文
```

**行为:**
- 调用 `ThemeService.resetToDefault()`
- 所有设置立即应用
- 返回上一页面
- 显示成功提示

---

## 📊 计算属性 (Computed Properties)

### `currentThemeColorName` - 获取当前主题色名称
```dart
String get currentThemeColorName {
  // 返回当前选中颜色的名称
  // 如果是自定义颜色，返回"自定义"
}

// 使用示例
Text('当前: ${controller.currentThemeColorName}');
// 输出: "当前: 蓝色" 或 "当前: 自定义"
```

### `currentFontSize` - 获取当前字体大小
```dart
double get currentFontSize => _themeService.fontSize.value;

// 使用示例
Text('字体大小: ${controller.currentFontSize.toStringAsFixed(1)}');
// 输出: "字体大小: 16.0"
```

### `isDarkMode` - 获取深色模式状态
```dart
bool get isDarkMode => _themeService.isDarkMode.value;

// 使用示例
Icon(isDarkMode ? Icons.brightness_2 : Icons.brightness_7)
```

### `currentAnimationIntensity` - 获取动画强度
```dart
double get currentAnimationIntensity => _themeService.animationIntensity.value;

// 使用示例
Text('动画强度: ${controller.currentAnimationIntensity.toStringAsFixed(1)}x')
// 输出: "动画强度: 1.5x"
```

### `currentLanguage` - 获取当前语言代码
```dart
String get currentLanguage => _themeService.currentLocale.value;

// 使用示例
if (controller.currentLanguage == 'en') {
  // 英文界面
}
```

---

## 📱 PersonalizationPage UI 参考

### 页面结构
```
CupertinoPageScaffold
├── navigationBar: CupertinoNavigationBar
│   └── middle: Text('个性化设置')
└── child: SafeArea
    └── Obx(() => ListView
        ├── 🎨 主题颜色部分
        │   ├── 标题
        │   ├── 颜色选择器网格
        │   └── 当前颜色显示
        ├── 📝 字体大小部分
        │   ├── 标题
        │   ├── 滑块
        │   └── 数值显示
        ├── 🌙 显示模式部分
        │   ├── 标题
        │   └── 深色模式开关
        ├── ✨ 动画效果部分
        │   ├── 标题
        │   └── 动画强度滑块
        ├── 🌐 语言部分
        │   ├── 标题
        │   └── 语言选择按钮组
        └── 🔄 恢复默认部分
            └── 恢复按钮
```

### 关键 Widget

#### 颜色选择器
```dart
GestureDetector(
  onTap: () => controller.setThemeColor(color),
  child: Container(
    // 圆形色块，选中时显示对勾
  ),
)
```

#### 字体大小滑块
```dart
CupertinoSlider(
  value: controller.currentFontSize,
  min: 12.0,
  max: 24.0,
  divisions: 12,
  onChanged: (value) => controller.setFontSize(value),
)
```

#### 深色模式开关
```dart
CupertinoSwitch(
  value: controller.isDarkMode,
  onChanged: (_) => controller.toggleDarkMode(),
)
```

---

## 🔗 与其他服务的关系

### ThemeService 集成
```dart
// PersonalizationController 使用 ThemeService 实现实际功能
_themeService = AppService.instance.theme;

// 常用方法调用
await _themeService.setPrimaryColor(color);
await _themeService.setFontSize(size);
await _themeService.toggleThemeMode();
await _themeService.setAnimationIntensity(intensity);
await _themeService.setLocale(locale);
await _themeService.resetToDefault();
```

### AnimationService 集成
```dart
// 获取动画服务
final animationService = AppService.instance.animation;

// 设置动画预设
animationService.setPreset(preset);
```

### AppService 访问
```dart
// PersonalizationController 通过 AppService 访问所有全局服务
final api = AppService.instance.api;
final storage = AppService.instance.storage;
final theme = AppService.instance.theme;
final animation = AppService.instance.animation;
```

---

## 🧪 测试用例

### 单元测试示例
```dart
test('setThemeColor should update primaryColor', () async {
  final controller = PersonalizationController();
  final color = Color(0xFF2196F3);
  
  await controller.setThemeColor(color);
  
  expect(controller.themeService.primaryColor.value, color);
});

test('setFontSize should update fontSize', () async {
  final controller = PersonalizationController();
  
  await controller.setFontSize(18.0);
  
  expect(controller.currentFontSize, 18.0);
});
```

### 集成测试示例
```dart
testWidgets('PersonalizationPage should toggle dark mode', (tester) async {
  await tester.pumpWidget(const MyApp());
  
  // 导航到个性化设置
  await tester.tap(find.text('个性化设置'));
  await tester.pumpAndSettle();
  
  // 找到深色模式开关
  final switchWidget = find.byType(CupertinoSwitch);
  
  // 点击开关
  await tester.tap(switchWidget);
  await tester.pumpAndSettle();
  
  // 验证背景色改变
  expect(find.byColor(Color(0xFF000000)), findsWidgets);
});
```

---

## 📋 速查表

| 方法 | 参数类型 | 返回类型 | 异步 |
|------|---------|---------|------|
| setThemeColor | Color | Future<void> | ✅ |
| setFontSize | double | Future<void> | ✅ |
| toggleDarkMode | - | Future<void> | ✅ |
| setAnimationIntensity | double | Future<void> | ✅ |
| setAnimationPreset | AnimationPreset | Future<void> | ✅ |
| setLanguage | String | Future<void> | ✅ |
| resetToDefaults | - | Future<void> | ✅ |

---

**文档版本**: 1.0  
**最后更新**: 2026-04-08  
**相关文件**: `lib/src/controllers/personalization_controller.dart`