kitchen/个性化设置API参考.md

📚 PersonalizationController API 参考文档

类定义

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

---

🎨 属性 (Properties)

颜色相关

themePresets - 主题颜色名称列表

final RxList<String> themePresets = RxList([
  '蓝色',
  '橙色',
  '蓝紫',
  '草绿',
  '深红',
]);

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

themePresetColors - 主题颜色值列表

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 - 动画预设名称列表

final RxList<String> animationPresets = RxList([
  '禁用',
  '低速',
  '标准',
  '高速',
]);

animationPresetValues - 动画预设枚举值列表

final RxList<AnimationPreset> animationPresetValues = RxList([
  AnimationPreset.none,      // 禁用
  AnimationPreset.slow,      // 低速
  AnimationPreset.standard,  // 标准
  AnimationPreset.fast,      // 高速
]);

语言相关

languageNames - 语言显示名称列表

final RxList<String> languageNames = RxList([
  '简体中文',
  '繁体中文',
  'English',
]);

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

languageCodes - 语言代码列表

final RxList<String> languageCodes = RxList([
  'zh',       // 简体中文
  'zh_Hant',  // 繁体中文
  'en',       // English
]);

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

---

🎯 方法 (Methods)

设置主题颜色

setThemeColor(Color color)

设置应用的主题颜色，颜色变化会立即应用到整个应用

参数:

• color Color - 要应用的颜色值

返回:

• Future<void> - 异步操作，等待保存完成

示例:

// 设置为蓝色
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> - 异步操作

示例:

// 设置为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> - 异步操作

示例:

// 简单切换
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> - 异步操作

示例:

// 设置为快速（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> - 异步操作

示例:

// 设置为高速
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> - 异步操作

示例:

// 切换为英文
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> - 异步操作

示例:

// 确认后恢复默认
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('确定'),
      ),
    ],
  ),
)

恢复到的默认值:

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 - 获取当前主题色名称

String get currentThemeColorName {
  // 返回当前选中颜色的名称
  // 如果是自定义颜色，返回"自定义"
}

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

currentFontSize - 获取当前字体大小

double get currentFontSize => _themeService.fontSize.value;

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

isDarkMode - 获取深色模式状态

bool get isDarkMode => _themeService.isDarkMode.value;

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

currentAnimationIntensity - 获取动画强度

double get currentAnimationIntensity => _themeService.animationIntensity.value;

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

currentLanguage - 获取当前语言代码

String get currentLanguage => _themeService.currentLocale.value;

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

---

📱 PersonalizationPage UI 参考

页面结构

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

关键 Widget

颜色选择器

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

字体大小滑块

CupertinoSlider(
  value: controller.currentFontSize,
  min: 12.0,
  max: 24.0,
  divisions: 12,
  onChanged: (value) => controller.setFontSize(value),
)

深色模式开关

CupertinoSwitch(
  value: controller.isDarkMode,
  onChanged: (_) => controller.toggleDarkMode(),
)

---

🔗 与其他服务的关系

ThemeService 集成

// 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 集成

// 获取动画服务
final animationService = AppService.instance.animation;

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

AppService 访问

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

---

🧪 测试用例

单元测试示例

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);
});

集成测试示例

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	✅
setFontSize	double	Future	✅
toggleDarkMode	-	Future	✅
setAnimationIntensity	double	Future	✅
setAnimationPreset	AnimationPreset	Future	✅
setLanguage	String	Future	✅
resetToDefaults	-	Future	✅

---

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