PyQt學習系列筆記（Python Qt框架）

第十一課：綜合項目 - 多語言文件管理器
（原課程規劃中的第十五課，按用戶要求調整為第十一課）

---

課程目標

1. 綜合運用PyQt框架開發一個支持多語言的文件管理器
2. 實現以下核心功能：
   • 文件瀏覽與目錄導航
   • 多線程文件搜索
   • 剪切板歷史記錄
   • 多語言切換（中/英）
   • 資源文件管理（圖標、樣式表）
3. 掌握**國際化（i18n）與本地化（l10n）**的完整實現流程

---

一、項目需求分析

1.1 功能需求

模塊	功能描述
文件瀏覽	顯示當前目錄下的文件和文件夾，支持雙擊進入子目錄
搜索功能	支持關鍵字搜索文件名，支持多線程加速
剪切板歷史	記錄最近10條剪切/復制內容，支持回溯
多語言切換	支持中/英文切換，界面文本自動更新
資源管理	使用.qrc文件管理圖標和樣式表

---

二、項目結構設計

multi_language_file_manager/
├── main.py                  # 主程序入口
├── ui/
│   └── main_window.ui       # Qt Designer設計的UI文件
├── resources/
│   ├── icons/               # 圖標資源
│   └── styles.qss           # 樣式表文件
├── i18n/
│   ├── en.ts                # 英文翻譯文件
│   └── zh.ts                # 中文翻譯文件
└── qrc/└── resources.qrc        # Qt資源文件

---

三、核心功能實現

3.1 使用Qt Designer設計界面

1. 打開Qt Designer，創建main_window.ui文件：

   • 添加QTreeView用于顯示文件目錄
   • 添加QLineEdit作為搜索輸入框
   • 添加QPushButton用于切換語言
   • 添加QListWidget顯示剪切板歷史

2. 保存UI文件后，使用pyuic5生成Python代碼：

   pyuic5 ui/main_window.ui -o ui/main_window.py
   

---

3.2 多語言支持實現

3.2.1 標記可翻譯文本

在代碼中使用tr()函數包裹所有需要翻譯的文本：

from PyQt5.QtCore import QCoreApplicationclass MainWindow(QMainWindow):def __init__(self):super().__init__()self.setWindowTitle(self.tr("多語言文件管理器"))  # 可翻譯標題self.search_button.setText(self.tr("搜索"))         # 可翻譯按鈕文本

---

3.2.2 生成翻譯文件

1. 創建.ts文件：

   pylupdate5 -noobsolete main.py -ts i18n/en.ts i18n/zh.ts
   

2. 使用Qt Linguist編輯翻譯：
   • 雙擊打開.ts文件，輸入對應語言的翻譯內容
   • 保存后生成.qm文件：

     lrelease i18n/en.ts i18n/zh.ts
     

---

3.2.3 動態加載語言包

from PyQt5.QtCore import QTranslator, QLocaledef load_language(language_code):translator = QTranslator()if translator.load(f"i18n/{language_code}.qm"):QCoreApplication.installTranslator(translator)# 重新加載UI以更新文本self.retranslateUi()

---

3.3 多線程文件搜索

1. 使用QThread實現后臺搜索：

from PyQt5.QtCore import QThread, pyqtSignal
import osclass SearchWorker(QThread):result_ready = pyqtSignal(str)def __init__(self, directory, keyword):super().__init__()self.directory = directoryself.keyword = keyworddef run(self):for root, dirs, files in os.walk(self.directory):for file in files:if self.keyword.lower() in file.lower():self.result_ready.emit(os.path.join(root, file))

2. 主線程連接信號：

worker = SearchWorker(current_dir, search_keyword)
worker.result_ready.connect(self.update_search_results)
worker.start()

---

3.4 剪切板歷史記錄

1. 監聽剪切板變化：

from PyQt5.QtGui import QClipboardclass ClipboardMonitor(QObject):clipboard_changed = pyqtSignal(str)def __init__(self):super().__init__()self.clipboard = QApplication.clipboard()self.clipboard.dataChanged.connect(self.on_clipboard_change)self.history = []def on_clipboard_change(self):text = self.clipboard.text()if text not in self.history:self.history.append(text)self.clipboard_changed.emit(text)

2. 限制歷史記錄數量：

if len(self.history) > 10:self.history.pop(0)

---

3.5 資源文件管理

1. 創建resources.qrc文件：

<RCC><qresource prefix="/"><file>icons/folder.png</file><file>icons/file.png</file><file>styles.qss</file></qresource>
</RCC>

2. 編譯資源文件：

pyrcc5 qrc/resources.qrc -o resources_rc.py

3. 加載資源文件：

import resources_rc  # 導入編譯后的資源
QFile(":/styles.qss").open(QFile.ReadOnly)
stylesheet = QFile.readAll()
self.setStyleSheet(stylesheet)

---

四、完整代碼示例

4.1 主程序入口（main.py）

import sys
from PyQt5.QtWidgets import QApplication
from ui.main_window import Ui_MainWindow
from i18n.translator import load_languageclass MainWindow(Ui_MainWindow, QMainWindow):def __init__(self):super().__init__()self.setupUi(self)self.init_ui()self.init_translator()def init_ui(self):# 初始化UI邏輯self.search_button.clicked.connect(self.start_search)def init_translator(self):self.translator = QTranslator()self.current_language = "en"self.load_language(self.current_language)def load_language(self, code):if self.translator.load(f"i18n/{code}.qm"):QCoreApplication.installTranslator(self.translator)self.retranslateUi()  # 更新UI文本def start_search(self):keyword = self.search_input.text()worker = SearchWorker(self.current_dir, keyword)worker.result_ready.connect(self.update_search_results)worker.start()if __name__ == "__main__":app = QApplication(sys.argv)window = MainWindow()window.show()sys.exit(app.exec_())

---

五、項目打包與部署

5.1 使用PyInstaller打包

1. 安裝依賴：

   pip install pyinstaller
   

2. 打包命令：

   pyinstaller -F -w --add-data "resources/*;resources" --icon=resources/icons/app_icon.ico main.py
   

3. 處理資源路徑問題：

   def resource_path(relative_path):if hasattr(sys, '_MEIPASS'):return os.path.join(sys._MEIPASS, relative_path)return os.path.join(os.path.abspath("."), relative_path)
   

---

六、常見問題與解決方案

6.1 多語言切換后UI未更新

• 原因：未調用retranslateUi()方法
• 解決方法：在切換語言后手動更新UI文本

---

6.2 搜索功能卡頓

• 原因：未使用多線程
• 解決方法：使用QThread或QRunnable分離搜索任務

---

6.3 資源文件無法加載

• 原因：路徑錯誤或未正確編譯.qrc文件
• 解決方法：
  1. 檢查pyrcc5是否成功生成resources_rc.py
  2. 在打包時使用--add-data參數包含資源目錄

---

七、總結與擴展

本項目綜合運用了以下技術點：

1. PyQt框架：實現文件管理器核心功能
2. 多語言支持：通過.ts文件和QTranslator實現國際化
3. 多線程：提升搜索性能
4. 資源管理：使用.qrc文件統一管理圖標和樣式表

擴展方向：

• 添加文件預覽功能（如圖片/文本預覽）
• 支持拖放操作
• 實現文件同步/備份功能

---

八、附錄：完整項目代碼倉庫

---

本系列課程到此結束！通過本課程的學習，您將掌握如何構建一個完整的多語言桌面應用，并為后續開發復雜軟件打下基礎！