Software_Architecture/src/Client/styles/USAGE_GUIDE.md

样式管理系统使用指南

🚀 快速开始

1. 基本集成

在任何Qt窗口或组件中使用现代样式管理器：

#include "styles/ModernStyleManager.h"

// 在构造函数中初始化
ModernStyleManager::getInstance()->applyTheme(
    ModernStyleManager::ThemeType::ModernMilitary
);

2. 便捷工具类

使用便捷工具类快速应用样式：

// 按钮样式
ModernStyleUtils::applyPrimaryButton(okButton);
ModernStyleUtils::applySuccessButton(saveButton);
ModernStyleUtils::applyWarningButton(warningButton);
ModernStyleUtils::applyDangerButton(deleteButton);

// 状态指示器
ModernStyleUtils::applyOnlineStatus(statusLabel);
ModernStyleUtils::applyOfflineStatus(statusLabel);
ModernStyleUtils::applyWarningStatus(statusLabel);

3. 演示模式

为课堂演示启用大字体模式：

// 启用演示模式
ModernStyleUtils::enablePresentationMode();

// 启用高对比度模式
ModernStyleUtils::enableHighContrastMode();

// 恢复正常模式
ModernStyleUtils::enableNormalMode();

🎨 主题系统

可用主题

// 现代军事主题（推荐）
styleManager->applyTheme(ThemeType::ModernMilitary);

// 经典军事主题
styleManager->applyTheme(ThemeType::ClassicMilitary);

// 学术主题
styleManager->applyTheme(ThemeType::Academic);

// 高对比度主题
styleManager->applyTheme(ThemeType::HighContrast);

显示模式

// 正常模式
styleManager->setDisplayMode(DisplayMode::Normal);

// 演示模式（大字体）
styleManager->setDisplayMode(DisplayMode::Presentation);

// 高对比度模式
styleManager->setDisplayMode(DisplayMode::HighContrast);

🔧 高级用法

1. 自定义按钮样式

ModernStyleManager* manager = ModernStyleManager::getInstance();

// 应用不同类型的按钮样式
manager->applyButtonStyle(button, ButtonStyle::Primary);
manager->applyButtonStyle(button, ButtonStyle::Success);
manager->applyButtonStyle(button, ButtonStyle::Warning);
manager->applyButtonStyle(button, ButtonStyle::Danger);
manager->applyButtonStyle(button, ButtonStyle::Info);

2. 设备状态管理

// 设置设备状态指示器
manager->setStatusIndicator(indicator, "online");
manager->setStatusIndicator(indicator, "offline");
manager->setStatusIndicator(indicator, "warning");

// 设置设备状态样式
manager->setDeviceStatus(deviceWidget, "online");

3. 动画效果

// 创建淡入动画
QPropertyAnimation* fadeIn = manager->createFadeInAnimation(widget, 500);
fadeIn->start();

// 创建滑入动画
QPropertyAnimation* slideIn = manager->createSlideInAnimation(widget, 1, 400);
slideIn->start();

// 使用便捷方法
ModernStyleUtils::playFadeInAnimation(widget);
ModernStyleUtils::playSlideInAnimation(widget);

4. 信号连接

// 监听主题应用完成
connect(styleManager, &ModernStyleManager::themeApplied,
        this, [](ThemeType theme, bool success) {
    if (success) {
        qDebug() << "主题应用成功:" << static_cast<int>(theme);
    }
});

// 监听显示模式变化
connect(styleManager, &ModernStyleManager::displayModeChanged,
        this, [](DisplayMode mode) {
    qDebug() << "显示模式变化:" << static_cast<int>(mode);
});

📱 组件样式应用

1. 输入控件

// 应用输入框样式
manager->applyInputStyle(lineEdit);

// 应用下拉框样式
manager->applyComboBoxStyle(comboBox);

2. 表格控件

// 应用表格样式
manager->applyTableStyle(tableWidget);

3. 设备面板

// 应用设备面板样式
manager->applyDevicePanelStyle(devicePanel);

// 应用设备卡片样式
manager->applyDeviceCardStyle(deviceCard);

🎯 最佳实践

1. 初始化顺序

void MyWindow::setupUI() {
    // 1. 创建UI组件
    createWidgets();
    
    // 2. 设置布局
    setupLayout();
    
    // 3. 应用样式（在组件创建后）
    initializeStyles();
    
    // 4. 连接信号槽
    connectSignals();
}

void MyWindow::initializeStyles() {
    ModernStyleManager* manager = ModernStyleManager::getInstance();
    manager->applyTheme(ThemeType::ModernMilitary);
    
    // 应用具体组件样式
    ModernStyleUtils::applyPrimaryButton(m_okButton);
    ModernStyleUtils::applyDangerButton(m_cancelButton);
}

2. 性能考虑

// ✅ 好的做法：批量样式应用
void applyAllStyles() {
    ModernStyleManager* manager = ModernStyleManager::getInstance();
    
    // 一次性应用主题
    manager->applyTheme(ThemeType::ModernMilitary);
    
    // 批量应用组件样式
    for (auto* button : m_buttons) {
        manager->applyButtonStyle(button, ButtonStyle::Primary);
    }
}

// ❌ 避免：频繁的样式切换
void badPractice() {
    for (int i = 0; i < 100; ++i) {
        manager->applyTheme(ThemeType::ModernMilitary);  // 避免在循环中频繁切换
    }
}

3. 内存管理

// 样式管理器会自动清理动画资源
// 但如果需要手动清理：
manager->cleanupAnimations();

// 刷新所有样式
manager->refreshAllStyles();

🐛 故障排除

常见问题

1. 样式不生效

   // 检查组件是否已创建
   if (button) {
       ModernStyleUtils::applyPrimaryButton(button);
   }
   
   // 确保在UI初始化后应用样式
   

2. CSS3错误

   // 使用现代主题避免CSS3兼容性问题
   manager->applyTheme(ThemeType::ModernMilitary);
   

3. 性能问题

   // 避免频繁的主题切换
   // 使用缓存机制
   QString currentTheme = manager->getCurrentStyleSheet();
   

调试方法

// 启用调试输出
qDebug() << "当前主题:" << static_cast<int>(manager->getCurrentTheme());
qDebug() << "当前显示模式:" << static_cast<int>(manager->getCurrentDisplayMode());
qDebug() << "样式表长度:" << manager->getCurrentStyleSheet().length();

// 检查动画数量
manager->cleanupAnimations();  // 会输出当前动画数量

📚 API参考

ModernStyleManager

方法	说明	示例
getInstance()	获取单例实例	auto* manager = ModernStyleManager::getInstance();
applyTheme()	应用主题	manager->applyTheme(ThemeType::ModernMilitary);
setDisplayMode()	设置显示模式	manager->setDisplayMode(DisplayMode::Presentation);
applyButtonStyle()	应用按钮样式	manager->applyButtonStyle(btn, ButtonStyle::Primary);

ModernStyleUtils

方法	说明	示例
applyPrimaryButton()	应用主要按钮样式	ModernStyleUtils::applyPrimaryButton(btn);
enablePresentationMode()	启用演示模式	ModernStyleUtils::enablePresentationMode();
playFadeInAnimation()	播放淡入动画	ModernStyleUtils::playFadeInAnimation(widget);

---

本指南涵盖了样式管理系统的主要用法。如需更多详细信息，请参考源码注释和README.md文档。