PyQt6 中文教程使用指南

一、核心价值：如何高效利用本教程资源？

本项目是 PyQt6 中文教程的文档源码仓库，提供从基础到进阶的完整学习路径。通过系统化的中文讲解和本地化资源，帮助开发者快速掌握 PyQt6 桌面应用开发技能。项目包含两种核心资源形态：

• 翻译文档：位于 translated/ 目录下，包含 PyQt5 和 PyQt6 两个版本的中文教程，按知识点分为界面组件、布局管理、事件处理等14个专题章节

• 教学图像：在 translated/pyqt5/images/ 和 translated/pyqt6/images/ 目录中，提供了100+张配套示意图，直观展示界面效果和代码运行结果，例如：

二、环境准备：如何构建本地化文档环境？

2.1 基础环境配置

本地预览需要安装 GitBook 工具链，按以下步骤操作：

1. 克隆项目代码库

git clone https://gitcode.com/gh_mirrors/py/PyQt-Chinese-tutorial.git
cd PyQt-Chinese-tutorial

2. 安装 Node.js 环境（建议 v14+），通过 npm 安装 GitBook CLI

npm install -g @gitbook-cli

3. 启动本地预览服务

gitbook serve

4. 在浏览器访问 http://localhost:4000 即可查看教程

2.2 文档版本控制

使用 Git 进行文档版本管理，核心操作包括：

• 查看提交历史：git log --pretty=oneline
• 创建翻译分支：git checkout -b translate-pyqt6-dialog
• 同步更新内容：git pull origin main
• 提交翻译成果：git commit -am "完成对话框章节翻译"

三、内容管理：如何高效组织学习路径？

3.1 资源组织最佳实践

项目采用清晰的模块化结构，建议按以下逻辑使用：

translated/
├── pyqt5/           # PyQt5 中文教程
│   ├── images/      # 配套截图（含控件效果、布局示例等）
│   ├── 事件和信号.md  # 事件处理机制详解
│   └── 布局管理.md    # 界面布局实现方法
├── pyqt6/           # PyQt6 中文教程
│   ├── dialogs.md   # 对话框组件文档
│   └── widgets2.md  # 高级控件使用指南
└── SUMMARY.md       # 教程总目录

3.2 个性化学习路径

根据学习目标选择不同章节组合：

• 入门路线：firstprograms.md → widgets.md → layout.md
• 进阶路线：eventssignals.md → painting.md → customwidgets.md
• 项目实践：直接查看 tetris.md 俄罗斯方块完整案例

四、高级配置：如何解决常见使用问题？

4.1 GitBook 构建错误处理

• 插件冲突：若启动时报错 Error: Couldn't load plugin，删除 node_modules 目录后重新安装

rm -rf node_modules
npm install

• 端口占用：使用 lsof -i:4000 查找占用进程，通过 kill -9 <PID> 释放端口

4.2 文档样式自定义

修改项目根目录的 gitbook.yaml 文件实现个性化配置：

title: PyQt6 中文教程
author: 社区贡献者
plugins:
  - search-pro      # 增强搜索功能
  - code           # 代码复制功能
  - page-toc       # 页面内目录
  - prism          # 代码高亮
lang: zh-CN

4.3 图片资源优化

对于教程中的图片资源，建议：

• 使用 PNG 格式保证清晰度
• 重要示意图添加文字标注
• 保持统一命名规范：章节编号-功能描述.png

通过以上配置，可构建功能完善的本地化 PyQt 学习环境，结合 14 个专题章节和丰富示例代码，助力快速掌握 PyQt6 开发技能。