不装 Word,也不用 python-docx:用 Python 标准库生成一个 DOCX 文件
我叫王仕宇 JavaPub。今天继续拆解我开源的 Copyright Forge Skill,聊一个很适合拿来练手的技术点:如何只用 Python 标准库,把文本变成 Word 文档。
不少人一看到“导出 Word”,首先想到安装 Office、调用办公软件,或者引入一个文档处理库。
但如果需求只是把整理好的文本按段落写入文档,设置字体,并插入明确的换页符,其实可以更轻量。
项目里的 render_source_docx.py 就采用了这条路线。
本文分析的是仓库提交
12ccf65中的基础 DOCX 导出实现,不是完整的办公排版引擎,也不代表材料可以直接通过登记审核。
一、先理解:DOCX 不是一整块神秘的二进制
打开源码可以看到,脚本没有导入 Word SDK,也没有引入 python-docx,而是使用 zipfile 写入三个文件:
[Content_Types].xml
_rels/.rels
word/document.xml
可以把这三部分简单理解成:
- 内容类型声明:告诉读取程序,包里有哪些类型的内容。
- 关系文件:告诉程序,正文文件在哪里。
- 正文 XML:保存段落、文字、字体以及页面设置。
这就是这个脚本生成文档的基本骨架。不是把 .txt 改个后缀,而是确实生成了包含文档结构的 ZIP 包。查看导出脚本
这个思路很值得学习:先弄清楚目标格式需要什么,再判断是否一定需要更重的依赖。
二、把“一行文本”变成“一个段落”
脚本中有一个 paragraph() 函数,负责把传入的文本转换为 WordprocessingML 段落。
它做的事情并不复杂:
- 对文字进行 XML 转义。
- 根据参数决定是否插入换页符。
- 设置段落间距和字体。
- 把文字放进文本节点。
简化后的结构如下。这里只展示阅读所需的骨架,不是可以单独使用的完整文档:
<w:p>
<w:r>
<w:rPr>
<w:rFonts w:ascii="Courier New" w:eastAsia="SimSun"/>
<w:sz w:val="14"/>
</w:rPr>
<w:t xml:space="preserve">这里是正文</w:t>
</w:r>
</w:p>
w:p 对应段落,w:r 对应一段具有相同格式的内容,w:t 保存文字。
项目对西文指定 Courier New,对东亚文字指定 SimSun。这些是字体请求,不等于已经把字体文件打包进文档;最终效果仍然需要在实际打开文档的环境中检查。
三、导出代码时,XML 转义不是可选项
源代码里经常出现这样的内容:
if a < b and c > d:
print("A&B")
如果直接把它拼进 XML,<、& 等字符可能破坏文档结构。
项目使用 html.escape() 先处理文字,再写入 XML。虽然函数名里有 html,这里利用的是它对特殊字符的转义能力。
还有一个容易被忽略的属性:
xml:space="preserve"
代码缩进本身有意义,不能把所有空白都当成多余内容。
不过,这里也有一个需要注意的实现边界:脚本在处理每一页时调用了 page.strip()。它会移除整页开头和结尾的空白。因此,不能把这个导出器描述成“对任意输入都逐字符无损保留”。如果某页直接以带缩进的代码开头,边界处空白就值得专门验证。
这也是我认为阅读小脚本很有价值的原因:功能越简单,细节越容易被看清楚。
四、亲手跑一遍最小示例
先获取开源项目:
git clone https://github.com/Rodert/copyright-forge-skill.git
cd copyright-forge-skill
下面用 Python 生成测试输入,避免手工输入换页控制字符:
python3 - <<'PY'
from pathlib import Path
content = (
'示例项目 V1.0\n'
'if a < b and c > d:\n'
' print("A&B")\n'
'\f'
'第二页\n'
' return True\n'
)
Path('../demo-source.txt').write_text(content, encoding='utf-8')
PY
再运行项目自带的导出脚本:
python3 skills/copyright-forge/scripts/render_source_docx.py \
../demo-source.txt \
--output ../demo-source.docx
这里把输出放在项目目录之外,避免把生成物混进源码。
你会得到 demo-source.docx。输入中的 \f 是换页分隔符,脚本会在后续页的首行前插入显式换页标记。它并不负责重新决定哪些代码应该进入材料,那是前面环节的职责。
五、不要只检查“文件存在”
生成一个文件,不代表文件内容一定正确。
可以先用标准库检查压缩包和 XML:
python3 - <<'PY'
from zipfile import ZipFile
import xml.etree.ElementTree as ET
with ZipFile('../demo-source.docx') as archive:
print(archive.namelist())
root = ET.fromstring(archive.read('word/document.xml'))
ns = {
'w': 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
}
print('换页标记数量:', len(root.findall('.//w:br', ns)))
print('文本内容:', [node.text for node in root.findall('.//w:t', ns)])
PY
这组样例已做过结构检查:压缩包包含上述三个文件,XML 可以解析,换页标记为 1 个,解析后的文本能够还原 <、> 和 &。
但这只是结构检查,不是完整视觉验收。真正交付前,还应打开文档,检查中文字体、长行、页边距和实际页数。
六、什么时候适合这条路线?
我的看法是,标准库直写 DOCX 适合边界明确的输出:
- 纯文本或源代码清单。
- 固定样式的基础报告。
- 依赖尽量少的命令行工具。
- 用于学习文档格式的练手项目。
如果需要复杂表格、目录、图片布局、页眉页脚或稳定的跨软件排版,就不要为了“零依赖”强行堆 XML 字符串。
在当前实现上继续改进,我会先考虑三件事:保留输入边界空白、检测超长行、加入真实办公软件的渲染验收。这些是扩展建议,不是仓库已经实现的能力。
最后
Copyright Forge Skill 是一个开源项目,仓库采用 Apache-2.0 许可证;使用和修改时,请遵守项目的许可证要求。查看许可证
对开发者来说,这个脚本最值得借鉴的并不只是“能导出 Word”。
而是它把内容准备与文件格式转换分开:前面的步骤确定写什么,最后的导出器只负责把内容装进一个清楚、可检查的结构中。
少一个依赖不是目的,让实现边界足够清楚才是。
转载自 CSDN-专业IT技术社区
原文链接:https://blog.csdn.net/qq_40374604/article/details/170775356



