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
.docfiles to modern.docxformat — 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 操作流程：
- 点击 「选择目录」 选择含
.doc文件的目录 - 勾选 「包含子目录」（可选）刷新列表
- 在文件列表中 多选 需要转换的文件（Ctrl/Shift 多选）
- 点击 「开始转换」，后台线程开始处理
- 完成后弹窗显示成功 / 失败数量，失败文件列表已自动写入 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 或改进文档！
- Fork 本仓库到你的账号
- 创建特性分支：
git checkout -b feat/your-feature - 提交代码：
git commit -m "feat: add your feature" - 推送到你的 Fork：
git push origin feat/your-feature - 在 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）
- 🐛 修复：剥离
infi.systray自动追加的Quit菜单项（其 callback 是字符串，点会抛 TypeError） - 🐛 修复：托盘退出时不能 join 自己线程；改用
os._exit(0)强制终止进程，确保「关于」窗口同时关闭 - 📦 EXE 文件名格式改为
ITGeekerConvertDocToDocx_v{version}.exe - 🏠 修复：传 ICO 而非 PNG 给
infi.systray.SysTrayIcon（之前显示默认图标） - 🪟 关于对话框改为单实例
- 🐛 修复：
Path.decode与dict.add错误（infi.systray 菜单更新）
v2.0.0.0（2026-07-28）
- ✨ 系统托盘：彩色 Emoji 图标 + 切换显示/隐藏 + 单实例关于对话框
- ✨ 窗口位置/大小持久化：退出时保存，下次启动自动恢复
- ✨ 关于对话框：可点击超链接
https://www.itgeeker.net - ✨ Forest 主题：明/暗切换 + 高 DPI ICO（16/32/48 多尺寸）
- 🔧 重构为根级 Python 包：
app / conversion / gui / persistence / theme / tray - 🔧 转换改为后台线程 +
after()轮询，UI 不再冻结 - 🔧 JSON 写入改为
tempfile+os.replace原子化，旧中文字段 100% 兼容 - 🔧 主题资源（forest-light/dark tcl + 138 PNG + 图标）移入包内，CWD 无关
- 🔧 消除
geekerWin/style模块级全局变量 - 🔧 默认窗口宽度改为
975px，标题栏/托盘使用统一图标 - 📦 PyInstaller 打包脚本：单文件 EXE，附带完整 Windows 版本信息
- 📦 54 个单元测试（persistence / conversion / tray / metadata）
- 🔧 修复
push.py（Python 2raw_input→ Python 3input，加__main__守卫）
v1.0.2.0（2023-06-13）
- ✨ 增加文件计数，并一同保存和预读
- 🔧 改写转换接口，当碰到错误文件时，记录错误，但并不中断继续转换
- ✨ 弹窗显示成功和失败的数量，及失败的文件列表，便于移除错误文件
v1.0.1.0（2023-06-12）
- 🐛 修复 Icon 文件错误问题，改用 base64 格式
- 📦 由于 PyInstaller 打包问题，改为安装包发行
v1.0.0.0（2023-06-11）
- 🎉 工具首发并已开源。
🔗 相关链接 / 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
