Open Source Office Word Document Format Converter

批量将 Word 旧版 .doc 文件转换为新版 .docx 格式 — 基于 Tkinter 与 Word COM 的 Windows 桌面小工具。

---

📖 项目简介 / Overview

开源Office Word格式转换工具 是由 技术奇客 ITGeeker.net 出品的 Office 系列小工具，专门解决企业、政务与教育场景下的 Word 旧格式兼容问题 —— 当你面对成百上千份历史遗留的 .doc 文件时，逐个用 Word 打开再"另存为"效率极低，本工具一键批量转换。

Batch-convert legacy Word .doc files to modern .docx format — a Tkinter + Word COM based Windows desktop utility.

🎯 解决什么痛点

• 🏢 企业迁移：旧系统留下的 .doc 文档需要快速升级到 .docx
• 📦 批量处理：一次扫描整个目录（含子目录），挑选后一键转换
• 💾 失败可查：损坏的 .doc 不中断任务，失败列表单独导出
• 🎨 现代化 UI：森林主题（明/暗）+ 系统托盘，操作不打扰当前工作

---

✨ 核心特性 / Features

• 🖱️ 一键批量转换 — 选定目录后列出所有 .doc（可含子目录），多选后后台线程并发处理，UI 不卡顿
• 🛡️ 失败容忍 — 单个文件损坏不会中断整个任务；失败列表写入 %USERPROFILE%\itgeeker_widget_config\config_doctodocx_failed.json
• 🎨 Forest 主题 — 采用 rdbende/Forest-ttk-theme，支持一键切换明/暗
• 🖥️ 系统托盘 — 关闭窗口最小化到托盘，右键菜单含彩色 Emoji 图标（🏠 显示 / 🙈 隐藏 / ℹ️ 关于 / 🚪 退出）
• 💾 状态持久化 — 自动记忆窗口位置/大小、上次目录、暗黑偏好、选中文件列表
• 📦 零依赖 EXE — PyInstaller 单文件打包，含完整 Windows 版本信息（公司/版权/网址），无需 Python 环境即可运行
• 🩺 统一版本元数据 — __version__ 单一来源，GUI 关于标签 / PyInstaller 版本信息 / pyproject.toml 自动同步
• 🪟 关于对话框 — 单实例、含可点击超链接 https://www.itgeeker.net

---

📸 效果演示 / Demo

暗黑主题

明亮主题

系统托盘（含彩色 Emoji 图标）
（截图占位 — 运行 dist/ITGeekerConvertDocToDocx_v2.0.0.1.exe 后右键托盘查看）

---

🚀 快速上手 / Getting Started

1️⃣ 环境准备 / Prerequisites

项目	要求
操作系统	Windows 10 / 11
Microsoft Office	2003 或更高版本（需 Word，工具通过 COM 调用）
Python（仅源码运行）	3.14+
包管理工具（推荐）	uv

2️⃣ 安装 / Installation

方式 A：直接下载 EXE（推荐普通用户）

从 Releases 页面下载最新的 ITGeekerConvertDocToDocx_v{version}.exe，双击运行即可。

方式 B：从源码运行（推荐开发者）

# 克隆仓库
git clone https://github.com/alanljj/itgeeker_convert_doc_to_docx.git
cd itgeeker_convert_doc_to_docx

# uv 会自动创建 .venv/ 并安装依赖（pywin32 等）
uv sync

# 启动 GUI（任意工作目录均可执行）
uv run main.py

启动成功后会在右下角系统托盘出现 🟠 图标，同时弹出主窗口。

3️⃣ 使用示例 / Usage

GUI 操作流程：

1. 点击 「选择目录」 选择含 .doc 文件的目录
2. 勾选 「包含子目录」（可选）刷新列表
3. 在文件列表中 多选 需要转换的文件（Ctrl/Shift 多选）
4. 点击 「开始转换」，后台线程开始处理
5. 完成后弹窗显示成功 / 失败数量，失败文件列表已自动写入 JSON

命令行启动方式（三选一）：

# 方式一：根目录入口脚本（推荐，最直观）
uv run main.py

# 方式二：通过 pyproject.toml [project.scripts] 注册的命令
uv run convert-doc-to-docx

# 方式三：以模块形式调用
uv run python -m app

---

⚙️ 配置说明 / Configuration

应用无需任何手动配置即可运行。所有用户偏好自动持久化到：

文件	内容
%USERPROFILE%\itgeeker_widget_config\config_doctodocx.json	窗口几何、上次目录、主题偏好、文件列表
%USERPROFILE%\itgeeker_widget_config\config_doctodocx_failed.json	上次失败的 .doc 文件列表（仅在有失败时生成）

💡 itgeeker_widget_config 子目录供多个 ITGeeker 工具共享，便于集中备份。

---

🛠️ 开发与发布 / Development & Release

项目结构

itgeeker_convert_doc_to_docx/
├── _meta.py / app.py / conversion.py / gui.py / main.py
│   └── persistence.py / theme.py / tray.py
├── assets\                    # 打包资源
│   ├── geekercloud_orange32.ico
│   ├── geekercloud_orange32.png
│   ├── converdoc_dark.png
│   └── converdoc_light.png
├── resources\                 # Forest 运行时主题
│   ├── forest-light.tcl + forest-light/*.png  (70)
│   └── forest-dark.tcl  + forest-dark/*.png   (68)
├── scripts\build_exe.py       # PyInstaller 打包脚本
├── tests\                     # 54 个单元测试
├── pyproject.toml             # PEP 621 元数据 + hatch 构建
├── README.md
└── LICENSE                     # MulanPSL-2.0

标准流程

# 1. 修改代码后，先用 Python 主文件测试
uv run main.py

# 2. 静态检查 + 单元测试
uv run ruff check .
uv run pytest

# 3. 静态检查通过后，按需打包（不是每次都打包）
uv sync --extra build
uv run python scripts/build_exe.py
# 输出：dist/ITGeekerConvertDocToDocx_v{version}.exe

⚠️ 打包是手动操作 — 不会自动触发。修改代码后请按上面 1-2 步测试，通过后才打包。

依赖 / Tech Stack

类型	包	说明
运行时	pywin32	调用 Word COM 转换 .doc → .docx
运行时	infi-systray	Windows 系统托盘（原生 Win32，支持菜单项彩色 Emoji 图标）
运行时	Pillow	彩色 Emoji 渲染 + PNG/ICO 处理
运行时	Tkinter (stdlib)	GUI + 主题
开发	pytest	54 个单元测试
开发	ruff	静态检查（PEP 8 / pyupgrade / bugbear 等）
打包	pyinstaller	单文件 EXE

---

🤝 贡献指南 / Contributing

欢迎贡献代码、报告 Bug 或改进文档！

1. Fork 本仓库到你的账号
2. 创建特性分支：git checkout -b feat/your-feature
3. 提交代码：git commit -m "feat: add your feature"
4. 推送到你的 Fork：git push origin feat/your-feature
5. 在 GitHub / Gitee 上发起 Pull Request

📌 开发纪律（来自项目记忆）：

不要随意删除项目目录里不是你创建的文件（详见 [[no-deletions]]）

修改前先 uv run pytest 跑通全部 54 个测试

提交前 uv run ruff check . 无警告

---

📜 开源协议 / License

本项目采用 木兰宽松许可证 第2版 (MulanPSL-2.0) 开源。

Copyright (c) 2023 技术奇客ITGeeker.net
https://www.itgeeker.net

详见 LICENSE 文件。

---

📝 更新日志 / Changelog

v2.0.0.1（2026-07-28）

1. 🐛 修复：剥离 infi.systray 自动追加的 Quit 菜单项（其 callback 是字符串，点会抛 TypeError）
2. 🐛 修复：托盘退出时不能 join 自己线程；改用 os._exit(0) 强制终止进程，确保「关于」窗口同时关闭
3. 📦 EXE 文件名格式改为 ITGeekerConvertDocToDocx_v{version}.exe
4. 🏠 修复：传 ICO 而非 PNG 给 infi.systray.SysTrayIcon（之前显示默认图标）
5. 🪟 关于对话框改为单实例
6. 🐛 修复：Path.decode 与 dict.add 错误（infi.systray 菜单更新）

v2.0.0.0（2026-07-28）

1. ✨ 系统托盘：彩色 Emoji 图标 + 切换显示/隐藏 + 单实例关于对话框
2. ✨ 窗口位置/大小持久化：退出时保存，下次启动自动恢复
3. ✨ 关于对话框：可点击超链接 https://www.itgeeker.net
4. ✨ Forest 主题：明/暗切换 + 高 DPI ICO（16/32/48 多尺寸）
5. 🔧 重构为根级 Python 包：app / conversion / gui / persistence / theme / tray
6. 🔧 转换改为后台线程 + after() 轮询，UI 不再冻结
7. 🔧 JSON 写入改为 tempfile + os.replace 原子化，旧中文字段 100% 兼容
8. 🔧 主题资源（forest-light/dark tcl + 138 PNG + 图标）移入包内，CWD 无关
9. 🔧 消除 geekerWin / style 模块级全局变量
10. 🔧 默认窗口宽度改为 975px，标题栏/托盘使用统一图标
11. 📦 PyInstaller 打包脚本：单文件 EXE，附带完整 Windows 版本信息
12. 📦 54 个单元测试（persistence / conversion / tray / metadata）
13. 🔧 修复 push.py（Python 2 raw_input → Python 3 input，加 __main__ 守卫）

v1.0.2.0（2023-06-13）

1. ✨ 增加文件计数，并一同保存和预读
2. 🔧 改写转换接口，当碰到错误文件时，记录错误，但并不中断继续转换
3. ✨ 弹窗显示成功和失败的数量，及失败的文件列表，便于移除错误文件

v1.0.1.0（2023-06-12）

1. 🐛 修复 Icon 文件错误问题，改用 base64 格式
2. 📦 由于 PyInstaller 打包问题，改为安装包发行

v1.0.0.0（2023-06-11）

1. 🎉 工具首发并已开源。

---

🔗 相关链接 / Links

• 🏠 项目主页：https://www.itgeeker.net
• 🐙 GitHub：https://github.com/alanljj/itgeeker_convert_doc_to_docx
• 🟢 Gitee：https://gitee.com/itgeeker/itgeeker_convert_doc_to_docx
• ☁️ GeekerCloud 奇客罗方智能科技：https://www.geekercloud.com
• 🎨 Forest ttk 主题：https://github.com/rdbende/Forest-ttk-theme

---

Made with ❤️ by 技术奇客 ITGeeker

Copyright © 2023-present · MulanPSL-2.0