# QtFileSync

**Repository Path**: dogdoog/qt-file-sync

## Basic Information

- **Project Name**: QtFileSync
- **Description**: 基于 Qt 框架开发的跨平台文件复制工具，采用多线程与信号槽机制实现高效、稳定的文件拷贝操作。项目通过独立的工作线程处理文件读写任务，有效避免界面卡顿，提升用户体验。客户端界面支持源文件与目标文件路径选择，实时显示复制进度，并具备完善的错误提示与状态恢复功能。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-12
- **Last Updated**: 2025-11-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FileSync - 跨平台文件复制工具

<div align="center">
<img src="https://img.shields.io/badge/📁_FileSync-文件复制工具-4A90E2?style=for-the-badge" alt="FileSync" width="600" height="80" />

*高效稳定，跨平台文件复制解决方案*

[![Qt Version](https://img.shields.io/badge/Qt-5.12%2B-brightgreen.svg)](https://www.qt.io/)
[![C++](https://img.shields.io/badge/C%2B%2B-11%2B-blue.svg)](https://isocpp.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux-lightgrey.svg)]()

## 📖 项目简介

FileSync 是一个基于Qt框架开发的跨平台文件复制工具，采用C++编写，支持大文件高效复制和实时进度显示。项目采用多线程架构，通过信号槽机制实现界面与文件操作的完美分离，提供流畅的用户体验。

## ✨ 主要特性

### 🚀 核心功能
- **多线程复制**：独立工作线程处理文件IO，避免界面卡顿
- **实时进度显示**：精确展示文件复制进度百分比
- **大文件支持**：分块读写策略，支持超大文件复制
- **跨平台运行**：可在Windows和Linux系统上稳定运行
- **错误恢复**：完善的异常处理和用户提示机制

### 🛡️ 技术特点
- **信号槽通信**：线程间安全通信，实时更新进度
- **资源管理**：自动内存管理和线程安全退出
- **文件校验**：复制前验证文件可读性和可写性
- **状态管理**：智能按钮状态控制，防止重复操作

### 🎨 用户体验
- **简洁界面**：直观的文件选择和操作界面
- **进度可视化**：实时进度条显示复制状态
- **友好提示**：清晰的操作指导和错误信息
- **一键操作**：简单的文件选择和复制流程

## 🏗️ 系统架构

### 应用架构
```
MainDialog (UI层)
    ↓
信号槽通信 (线程间通信)
    ↓
Worker类 (工作线程)
    ↓
QFile操作 (文件IO层)
    ↓
分块读写 (数据处理)
```

### 线程模型
```
UI线程 (主线程)
    ├── 用户交互处理
    ├── 进度显示更新
    └── 错误提示显示
        ↓
工作线程 (QThread)
    ├── 文件读取
    ├── 数据写入
    └── 进度计算
```

## 📦 安装与运行

### 环境要求
- **Qt版本**: 5.12 或更高版本
- **编译器**: 
  - Windows: MinGW 或 MSVC
  - Linux: GCC 4.8+
- **C++标准**: C++11 或更高

### 编译步骤

1. **获取项目代码**
   ```bash
   git clone https://gitee.com/dogdoog/qt-file-sync.git
   cd FileSync
   ```

2. **使用Qt Creator打开**
   
   - 打开 `FileSync.pro` 文件
   - 选择对应的编译套件
- 点击"构建"按钮编译项目
   
3. **命令行编译**
   ```bash
   qmake FileSync.pro
   make
   # Windows MSVC 使用 nmake
   ```

### 运行说明

1. **启动应用**
   ```bash
   ./FileSync    # Linux
   FileSync.exe  # Windows
   ```

2. **使用流程**
   - 点击"选择源文件"按钮选择要复制的文件
   - 点击"选择目标文件"按钮指定保存路径
   - 点击"开始拷贝"按钮启动复制过程
   - 在进度条中查看实时复制进度

## 🔧 核心代码说明

### 多线程实现
```cpp
// 创建工作线程
copyThr = new QThread(this);
Worker* w = new Worker();
w->moveToThread(copyThr);

// 连接信号槽
connect(this, &MainDialog::startCopy, w, &Worker::copyFile);
connect(w, &Worker::updateCopyProgress, this, &MainDialog::updateCopyProgress);
```

### 文件复制逻辑
```cpp
// 分块读写，实时更新进度
while((ret = f1.read(buff, sizeof(buff))) > 0) {
    f2.write(buff, ret);
    copyedCnt += ret;
    curProgress = 100.0 * copyedCnt / fileSize;
    emit updateCopyProgress(curProgress);
}
```

## 📋 使用指南

### 基本操作
1. **选择源文件**：点击"选择源文件"按钮，选择要复制的文件
2. **选择目标路径**：点击"选择目标文件"按钮，指定保存位置
3. **开始复制**：点击"开始拷贝"按钮启动复制过程
4. **监控进度**：通过进度条实时查看复制进度

### 注意事项
- 确保源文件具有读取权限
- 确保目标路径具有写入权限
- 复制过程中请勿关闭应用程序
- 大文件复制可能需要较长时间

## 🔍 技术细节

### 多线程通信机制
- **进度更新**：工作线程通过信号实时发送进度信息
- **任务完成**：复制完成后发送完成信号恢复界面状态
- **错误处理**：异常情况通过消息框提示用户

### 文件处理策略
- **缓冲区优化**：使用4KB缓冲区平衡性能和内存使用
- **进度计算**：基于文件大小和已复制字节数计算进度
- **资源释放**：复制完成后自动关闭文件句柄

## 🐛 故障排除

### 常见问题

1. **文件无法打开**
   - 检查文件是否被其他程序占用
   - 确认用户具有文件读写权限
   - 验证文件路径是否正确

2. **复制进度卡住**
   - 检查磁盘空间是否充足
   - 确认目标路径可写
   - 验证文件系统完整性

3. **编译错误**
   - 确认Qt版本符合要求
   - 检查编译器支持C++11标准
   - 验证项目配置正确

## 👥 开发团队

- **项目发起人**: 杨家翔
- **核心开发**: 杨家翔
- **测试维护**: 杨家翔

## 📞 联系信息

- **邮箱联系**: 15097601713@163.com

## 🎯 未来规划

- [ ] 支持文件夹递归复制
- [ ] 添加复制速度显示和预估时间
- [ ] 实现复制任务队列管理
- [ ] 支持复制过程暂停和恢复
- [ ] 添加文件校验和完整性验证
- [ ] 开发命令行版本
- [ ] 支持网络文件复制功能

## 📊 性能表现

- **复制速度**: 充分利用系统IO性能
- **内存占用**: 固定4KB缓冲区，内存占用稳定
- **CPU使用**: 多线程设计，界面响应流畅
- **稳定性**: 完善的错误处理和资源管理