cutThenThink/docs/gui_main_window.md

# 主窗口框架实现文档

## 概述

P0-6 任务已完成，实现了应用程序的主窗口框架，包括侧边栏导航、主内容区域和米白色配色方案。

## 已实现的文件

### 1. `src/gui/main_window.py`

主窗口实现，包含以下组件：

#### 类
- **`MainWindow`**: 主窗口类
  - 窗口标题："CutThenThink - 智能截图管理"
  - 默认大小：1200x800
  - 最小大小：1000x700

- **`NavigationButton`**: 导航按钮类
  - 支持图标和文本
  - 可选中状态
  - 悬停效果

#### 功能
1. **侧边栏导航**
   - 📷 截图处理
   - 📁 分类浏览
   - ☁️ 批量上传
   - ⚙️ 设置

2. **主内容区域**
   - 使用 `QStackedWidget` 实现页面切换
   - 四个独立页面：截图处理、分类浏览、批量上传、设置
   - 响应式布局，支持窗口大小调整

3. **页面设计**
   - **截图处理页面**：欢迎卡片、快捷操作按钮
   - **分类浏览页面**：浏览功能介绍
   - **批量上传页面**：上传功能介绍
   - **设置页面**：使用滚动区域，包含 AI、OCR、云存储、界面配置

### 2. `src/gui/styles/colors.py`

颜色方案定义，采用温暖的米白色系：

```python
# 主色调 - 米白色系
background_primary: "#FAF8F5"    # 主背景色
background_secondary: "#F0ECE8"  # 次要背景色
background_card: "#FFFFFF"       # 卡片背景色

# 文字颜色
text_primary: "#2C2C2C"          # 主要文字
text_secondary: "#666666"        # 次要文字

# 强调色 - 温暖的棕色系
accent_primary: "#8B6914"        # 主要强调色 - 金棕
accent_secondary: "#A67C52"      # 次要强调色 - 驼色
```

#### 类和函数
- **`ColorScheme`**: 颜色方案数据类
- **`COLORS`**: 全局颜色方案实例
- **`get_color(name)`**: 获取颜色值的快捷函数

### 3. `src/gui/styles/theme.py`

主题样式表（QSS），定义完整的 UI 样式：

#### 样式覆盖
- 主窗口
- 侧边栏和导航按钮
- 主内容区域
- 按钮（主要/次要）
- 输入框和文本框
- 下拉框
- 滚动条
- 分组框
- 标签页
- 复选框和单选框
- 进度条
- 菜单
- 列表
- 状态栏
- 工具提示

#### 类和方法
- **`ThemeStyles`**: 主题样式表类
  - `get_main_window_stylesheet()`: 获取主窗口样式表
  - `apply_style(widget)`: 应用样式到部件

### 4. `src/gui/styles/__init__.py`

样式模块的导出接口，统一导出：
- `ColorScheme`
- `COLORS`
- `get_color`
- `ThemeStyles`

### 5. `src/gui/__init__.py`

GUI 模块导出，使用延迟导入避免 PyQt6 依赖问题：
- 样式模块直接导入
- 主窗口通过 `get_main_window_class()` 延迟导入

## 使用示例

### 基本使用

```python
from PyQt6.QtWidgets import QApplication
from src.gui import get_main_window_class

# 创建应用程序
app = QApplication([])

# 获取主窗口类并创建实例
MainWindow = get_main_window_class()
window = MainWindow()
window.show()

app.exec()
```

### 直接使用样式

```python
from src.gui.styles import COLORS, ThemeStyles
from PyQt6.QtWidgets import QPushButton

# 使用颜色
button = QPushButton("按钮")
button.setStyleSheet(f"""
    QPushButton {{
        background-color: {COLORS.accent_primary};
        color: {COLORS.button_primary_text};
    }}
""")

# 应用完整主题
from src.gui import get_main_window_class
MainWindow = get_main_window_class()
window = MainWindow()
window.show()
```

## 设计特点

### 1. 米白色配色方案
- 温暖、舒适的视觉体验
- 适合长时间使用
- 专业的界面呈现

### 2. 模块化设计
- 样式与逻辑分离
- 颜色统一管理
- 易于维护和扩展

### 3. 响应式布局
- 自适应窗口大小
- 支持不同屏幕分辨率
- 优雅的空间利用

### 4. 完整的样式覆盖
- 所有 Qt 部件都有统一样式
- 支持悬停、选中、禁用等状态
- 符合现代 UI 设计规范

## 后续扩展

### 短期（P1 任务）
1. 实现截图处理页面的实际功能
2. 添加分类浏览页面的内容展示
3. 实现批量上传功能
4. 完善设置页面的配置项

### 长期
1. 添加深色主题支持
2. 实现自定义主题
3. 添加动画效果
4. 国际化支持

## 测试

运行测试脚本查看效果（需要安装 PyQt6）：

```bash
# 安装依赖
pip install -r requirements.txt

# 运行测试
python3 test_main_window.py
```

## 技术栈

- **GUI 框架**: PyQt6
- **样式**: QSS (Qt Style Sheets)
- **Python 版本**: 3.8+

## 注意事项

1. 需要 PyQt6 才能运行主窗口
2. 样式模块可以独立导入，不需要 PyQt6
3. 主窗口类使用延迟导入，避免模块加载时的依赖问题
4. 所有颜色和样式统一在 `styles` 模块中管理

## 相关文件

- `/home/congsh/CodeSpace/ClaudeSpace/CutThenThink/src/gui/main_window.py`
- `/home/congsh/CodeSpace/ClaudeSpace/CutThenThink/src/gui/styles/colors.py`
- `/home/congsh/CodeSpace/ClaudeSpace/CutThenThink/src/gui/styles/theme.py`
- `/home/congsh/CodeSpace/ClaudeSpace/CutThenThink/src/gui/styles/__init__.py`
- `/home/congsh/CodeSpace/ClaudeSpace/CutThenThink/src/gui/__init__.py`
- `/home/congsh/CodeSpace/ClaudeSpace/CutThenThink/test_main_window.py`