# ShortVideoClient

**Repository Path**: liuss-44/ShortVideoClient

## Basic Information

- **Project Name**: ShortVideoClient
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 109
- **Created**: 2026-06-08
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 抖音短视频客户端 - PyQt6 实现

## 项目简介

这是一个基于 PyQt6 开发的简易短视频客户端，模仿抖音官网的界面设计。作为教学项目，它展示了：
- PyQt6 GUI 开发基础
- 自定义布局算法（FlowLayout）
- 组件化设计与 QSS 样式系统
- 数据驱动的 UI 渲染

## 功能特性

✅ **三栏布局**：左侧边栏 + 顶部栏 + 主内容区  
✅ **响应式流式布局**：视频卡片自动根据窗口大小调整排列  
✅ **深色主题**：白色字体，红色高亮（#fe2c55）  
✅ **视频卡片**：显示缩略图、标题、作者、发布时间  
✅ **悬停效果**：鼠标悬停时卡片显示红色边框  
✅ **搜索过滤**：实时根据标题或作者过滤视频  
✅ **导航切换**：精选、推荐、关注、热榜（占位）  

## 技术栈

- **Python**: >= 3.8
- **PyQt6**: >= 6.5.0
- **布局**: 自定义 FlowLayout（参考 Qt 官方示例）
- **样式**: QSS (Qt Style Sheets)
- **数据**: JSON 配置文件

## 项目结构

```
ShortVideoClient/
├── src/
│   ├── main.py                 # 程序入口
│   ├── styles.qss              # QSS 样式文件
│   ├── data/
│   │   └── videos.json         # 视频元数据配置（16条）
│   ├── widgets/
│   │   ├── __init__.py
│   │   ├── flow_layout.py      # 自定义流式布局
│   │   ├── video_card.py       # 视频卡片组件
│   │   ├── sidebar.py          # 左侧边栏
│   │   ├── topbar.py           # 顶部栏
│   │   └── main_window.py      # 主窗口
│   ├── images/                 # 图片资源
│   │   ├── card*.jpeg          # 视频缩略图（16张）
│   │   ├── logo.png            # Logo
│   │   └── home/recommend/follow/hot*.png  # 导航图标
│   └── videos/                 # 视频资源
│       └── sample*.mp4         # 视频文件（7个）
├── openspec/                   # OpenSpec 文档
│   └── changes/
│       └── 抖音短视频客户端主界面/
│           ├── proposal.md     # 提案概述
│           ├── design.md       # 技术设计
│           ├── specs/          # 功能规范
│           └── tasks.md        # 任务清单
└── README.md
```

## 安装与运行

### 1. 安装依赖

```bash
pip install PyQt6
```

### 2. 运行程序

```bash
cd src
python main.py
```

### 3. 验收测试

启动后验证以下功能：

- [ ] 窗口正常启动，显示完整三栏布局
- [ ] 左侧边栏固定宽度 180px，包含 4 个导航项
- [ ] 顶部栏显示 Logo、搜索框、登录按钮
- [ ] 主内容区以流式布局展示 16 个视频卡片
- [ ] 拖动窗口 resize 时卡片自动重新排列（换行、调整数量）
- [ ] 视频卡片显示缩略图、标题、作者、发布时间
- [ ] 鼠标悬停卡片时有红色边框高亮
- [ ] 点击侧边栏导航项切换选中状态（红色背景）
- [ ] 搜索框输入文字时实时过滤视频卡片
- [ ] 整体深色主题，白色字体，红色高亮正确应用

## 核心设计

### 1. 自定义 FlowLayout

实现了类似 CSS Flexbox 的流式布局：
- 自动根据容器宽度计算每行可容纳的卡片数
- 超出边界时自动换行
- 支持动态间距设置

**关键代码**：`src/widgets/flow_layout.py` 中的 `_do_layout()` 方法

### 2. 组件化架构

```
MainWindow (组装所有组件)
├── SideBar (左侧导航)
│   └── NavButton x4 (导航按钮)
├── TopBar (顶部栏)
│   ├── Logo Label
│   ├── SearchBox (QLineEdit)
│   └── LoginButton
└── ContentArea (QScrollArea)
    └── FlowLayout (自定义布局)
        └── VideoCard x16 (视频卡片)
```

### 3. 信号槽通信

- `TopBar.search_text_changed` → `MainWindow._filter_cards()`
- `SideBar.page_changed` → `MainWindow._on_page_changed()`
- `VideoCard.card_clicked` → `MainWindow._on_card_clicked()`

### 4. 数据驱动

从 `src/data/videos.json` 加载视频元数据，随机分配视频文件和缩略图：

```json
{
  "id": "video_1",
  "title": "Python编程入门教程",
  "author": "编程学院",
  "publish_time": "2024-01-15"
}
```

## 扩展建议

当前版本仅实现 UI 展示，可扩展功能包括：

1. **视频播放**：集成 `QMediaPlayer` + `QVideoWidget`
2. **用户认证**：实现登录对话框和用户状态管理
3. **后端集成**：从 API 获取视频数据
4. **无限滚动**：分页加载更多内容
5. **社交功能**：点赞、评论、分享按钮
6. **个性化推荐**：根据用户行为推荐视频

## 教学要点

### PyQt6 核心概念
- QWidget 继承体系
- 布局管理器（QVBoxLayout, QHBoxLayout, 自定义 Layout）
- 信号槽机制（pyqtSignal）
- 事件处理（enterEvent, leaveEvent, mousePressEvent）
- QSS 样式表

### 工程实践
- 模块化组件设计
- 数据与视图分离
- 异常处理
- 资源管理（图片、文件路径）

### 算法思维
- FlowLayout 布局算法
- 搜索过滤算法
- 随机资源分配

## 常见问题

### Q: 窗口空白，没有显示卡片？
A: 检查控制台输出，确认是否找到视频文件和缩略图。如果路径错误，会显示 0 个资源。

### Q: 图片显示不出来？
A: 确保 `src/images/card*.jpeg` 文件存在。如果加载失败，卡片会显示灰色占位符。

### Q: 样式没有生效？
A: 确认 `src/styles.qss` 文件存在且格式正确。检查控制台是否有"样式表加载成功"的提示。

### Q: 窗口太小，卡片重叠？
A: 窗口最小尺寸设置为 800x600，如果仍然有问题，检查 FlowLayout 的间距设置。

## 参考资料

- PyQt6 官方文档：https://www.riverbankcomputing.com/static/Docs/PyQt6/
- Qt Flow Layout 示例：https://doc.qt.io/qt-6/qtwidgets-layouts-flowlayout-example.html
- QSS 样式表指南：https://doc.qt.io/qt-6/stylesheet-reference.html

## 许可证

本项目为教学用途，仅供学习参考。