You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Software_Architecture/src/Client/styles/USAGE_GUIDE.md

297 lines
6.9 KiB

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 样式管理系统使用指南
## 🚀 快速开始
### 1. 基本集成
在任何Qt窗口或组件中使用现代样式管理器
```cpp
#include "styles/ModernStyleManager.h"
// 在构造函数中初始化
ModernStyleManager::getInstance()->applyTheme(
ModernStyleManager::ThemeType::ModernMilitary
);
```
### 2. 便捷工具类
使用便捷工具类快速应用样式:
```cpp
// 按钮样式
ModernStyleUtils::applyPrimaryButton(okButton);
ModernStyleUtils::applySuccessButton(saveButton);
ModernStyleUtils::applyWarningButton(warningButton);
ModernStyleUtils::applyDangerButton(deleteButton);
// 状态指示器
ModernStyleUtils::applyOnlineStatus(statusLabel);
ModernStyleUtils::applyOfflineStatus(statusLabel);
ModernStyleUtils::applyWarningStatus(statusLabel);
```
### 3. 演示模式
为课堂演示启用大字体模式:
```cpp
// 启用演示模式
ModernStyleUtils::enablePresentationMode();
// 启用高对比度模式
ModernStyleUtils::enableHighContrastMode();
// 恢复正常模式
ModernStyleUtils::enableNormalMode();
```
## 🎨 主题系统
### 可用主题
```cpp
// 现代军事主题(推荐)
styleManager->applyTheme(ThemeType::ModernMilitary);
// 经典军事主题
styleManager->applyTheme(ThemeType::ClassicMilitary);
// 学术主题
styleManager->applyTheme(ThemeType::Academic);
// 高对比度主题
styleManager->applyTheme(ThemeType::HighContrast);
```
### 显示模式
```cpp
// 正常模式
styleManager->setDisplayMode(DisplayMode::Normal);
// 演示模式(大字体)
styleManager->setDisplayMode(DisplayMode::Presentation);
// 高对比度模式
styleManager->setDisplayMode(DisplayMode::HighContrast);
```
## 🔧 高级用法
### 1. 自定义按钮样式
```cpp
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. 设备状态管理
```cpp
// 设置设备状态指示器
manager->setStatusIndicator(indicator, "online");
manager->setStatusIndicator(indicator, "offline");
manager->setStatusIndicator(indicator, "warning");
// 设置设备状态样式
manager->setDeviceStatus(deviceWidget, "online");
```
### 3. 动画效果
```cpp
// 创建淡入动画
QPropertyAnimation* fadeIn = manager->createFadeInAnimation(widget, 500);
fadeIn->start();
// 创建滑入动画
QPropertyAnimation* slideIn = manager->createSlideInAnimation(widget, 1, 400);
slideIn->start();
// 使用便捷方法
ModernStyleUtils::playFadeInAnimation(widget);
ModernStyleUtils::playSlideInAnimation(widget);
```
### 4. 信号连接
```cpp
// 监听主题应用完成
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. 输入控件
```cpp
// 应用输入框样式
manager->applyInputStyle(lineEdit);
// 应用下拉框样式
manager->applyComboBoxStyle(comboBox);
```
### 2. 表格控件
```cpp
// 应用表格样式
manager->applyTableStyle(tableWidget);
```
### 3. 设备面板
```cpp
// 应用设备面板样式
manager->applyDevicePanelStyle(devicePanel);
// 应用设备卡片样式
manager->applyDeviceCardStyle(deviceCard);
```
## 🎯 最佳实践
### 1. 初始化顺序
```cpp
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. 性能考虑
```cpp
// ✅ 好的做法:批量样式应用
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. 内存管理
```cpp
// 样式管理器会自动清理动画资源
// 但如果需要手动清理:
manager->cleanupAnimations();
// 刷新所有样式
manager->refreshAllStyles();
```
## 🐛 故障排除
### 常见问题
1. **样式不生效**
```cpp
// 检查组件是否已创建
if (button) {
ModernStyleUtils::applyPrimaryButton(button);
}
// 确保在UI初始化后应用样式
```
2. **CSS3错误**
```cpp
// 使用现代主题避免CSS3兼容性问题
manager->applyTheme(ThemeType::ModernMilitary);
```
3. **性能问题**
```cpp
// 避免频繁的主题切换
// 使用缓存机制
QString currentTheme = manager->getCurrentStyleSheet();
```
### 调试方法
```cpp
// 启用调试输出
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文档。*