JSON 转 Word 并不是格式层面的“转换”,而是一次结构映射:JSON 的键值对、嵌套对象、对象数组,需要被翻译成段落、标题、表格这些人类可读的文档组件。Python 的 json 模块负责解析数据,文档库负责把解析后的结构装配成 .docx。本文以 Free Spire.Doc for Python 免费库为例,介绍如何将 JSON 数据导出为 Word 文档。
一、安装
pip install Spire.Doc.Free
这个包独立于 Microsoft Word 运行,适合学习、脚本化报告生成和轻量自动化场景。
二、先理解对象模型
在写映射代码之前,理清文档的对象树比急着调用 API 更重要:
Document:整个文档的根对象。Section:页面级容器,页边距、页眉页脚在这一层设置。Paragraph:块级内容单位,所有可见文字都挂在段落上。TextRange:段落内一段连续文本的格式控制入口。
字符级格式(字体、字号、加粗、颜色)设在 TextRange.CharacterFormat 上;段落级格式(对齐、缩进、段前段后间距)设在 Paragraph.Format 上。表格单元格里的段落同样适用这套规则。
三、映射原则:结构决定形态
| JSON 结构 | Word 元素 | 典型场景 |
|---|---|---|
| 扁平对象的键值对 | 段落(标签:值) | 元信息、配置快照 |
| 嵌套对象(dict) | 小标题 + 逐行标签 | 负责人信息、层级摘要 |
| 对象数组 | 表格(键→列标题,对象→行) | 员工列表、订单、库存 |
| 图片路径字段 | 内联图片 | Logo、图表快照 |
先确定映射规则,再写代码,比边写边调更可控。
四、准备 JSON 数据
数据可以内嵌为字符串、从文件读取,或从 API 获取。下面的例子是一份中文员工目录报告,注意其中 负责人 是嵌套对象(dict),团队 是对象数组,二者在 Word 中会呈现为完全不同的形态。
import json
json_data = '''{
"公司": "星澜科技有限公司",
"部门": "研发部",
"报告日期": "2026年11月17日",
"负责人": {
"姓名": "张敏",
"职位": "研发副总裁",
"邮箱": "zhang.min@xinglan.com"
},
"概览": "研发部目前有 5 名在职成员,分布在三个办公地点。所有项目均按计划推进。",
"团队": [
{"姓名": "王磊", "职位": "高级开发工程师", "邮箱": "wang.lei@xinglan.com", "办公地点": "北京"},
{"姓名": "李婷", "职位": "前端开发工程师", "邮箱": "li.ting@xinglan.com", "办公地点": "上海"},
{"姓名": "陈昊", "职位": "后端开发工程师", "邮箱": "chen.hao@xinglan.com", "办公地点": "深圳"},
{"姓名": "赵雪", "职位": "测试工程师", "邮箱": "zhao.xue@xinglan.com", "办公地点": "北京"},
{"姓名": "周航", "职位": "运维工程师", "邮箱": "zhou.hang@xinglan.com", "办公地点": "杭州"}
]
}'''
data = json.loads(json_data)
如果 JSON 存放在文件里,把字符串替换为:
with open('report.json', 'r', encoding='utf-8') as f:
data = json.load(f)
五、转换脚本:从标题到表格
完整脚本分为七个步骤:加载数据、创建文档与样式、写主标题、写概览、渲染嵌套对象、渲染数组表格、保存。
import json
from spire.doc import (
Document, FileFormat, HorizontalAlignment,
VerticalAlignment, TableRowHeightType, Color,
BuiltinStyle
)
# --- 1. 加载 JSON ---
json_data = '''{
"公司": "星澜科技有限公司",
"部门": "研发部",
"报告日期": "2026年11月17日",
"负责人": {
"姓名": "张敏",
"职位": "研发副总裁",
"邮箱": "zhang.min@xinglan.com"
},
"概览": "研发部目前有 5 名在职成员,分布在三个办公地点。所有项目均按计划推进。",
"团队": [
{"姓名": "王磊", "职位": "高级开发工程师", "邮箱": "wang.lei@xinglan.com", "办公地点": "北京"},
{"姓名": "李婷", "职位": "前端开发工程师", "邮箱": "li.ting@xinglan.com", "办公地点": "上海"},
{"姓名": "陈昊", "职位": "后端开发工程师", "邮箱": "chen.hao@xinglan.com", "办公地点": "深圳"},
{"姓名": "赵雪", "职位": "测试工程师", "邮箱": "zhao.xue@xinglan.com", "办公地点": "北京"},
{"姓名": "周航", "职位": "运维工程师", "邮箱": "zhou.hang@xinglan.com", "办公地点": "杭州"}
]
}'''
data = json.loads(json_data)
# --- 2. 创建文档与样式 ---
document = Document()
section = document.AddSection()
heading_style = document.AddStyle(BuiltinStyle.Heading1)
subheading_style = document.AddStyle(BuiltinStyle.Heading2)
# --- 3. 主标题(扁平字段) ---
title_para = section.AddParagraph()
title_para.ApplyStyle(heading_style.Name)
title_para.AppendText(
f"{data.get('公司', '公司')} — {data.get('部门', '部门')}人员目录"
)
date_para = section.AddParagraph()
date_para.AppendText(f"报告日期:{data.get('报告日期', '未提供')}")
date_para.Format.AfterSpacing = 16
# --- 4. 概览段落 ---
overview_heading = section.AddParagraph()
overview_heading.ApplyStyle(subheading_style.Name)
overview_heading.AppendText("部门概览")
overview_para = section.AddParagraph()
overview_para.AppendText(data.get("概览", ""))
overview_para.Format.AfterSpacing = 16
# --- 5. 负责人信息(嵌套对象 → 逐行标签) ---
manager = data.get("负责人", {})
if manager:
manager_heading = section.AddParagraph()
manager_heading.ApplyStyle(subheading_style.Name)
manager_heading.AppendText("部门负责人")
for key in ["姓名", "职位", "邮箱"]:
line = section.AddParagraph()
line.AppendText(f"{key}:{manager.get(key, '未提供')}")
line.Format.AfterSpacing = 4
# 负责人区块之后留出额外间距
section.AddParagraph().Format.AfterSpacing = 8
# --- 6. 团队成员表格(对象数组 → 表格) ---
team_heading = section.AddParagraph()
team_heading.ApplyStyle(subheading_style.Name)
team_heading.AppendText("团队成员")
team = data.get("团队", [])
if team:
headers = list(team[0].keys()) # 中文键直接作为列标题
table = section.AddTable(True) # True = 带边框
table.ResetCells(len(team) + 1, len(headers)) # +1 为表头行
# 表头行
header_row = table.Rows[0]
header_row.IsHeader = True
header_row.Height = 20
header_row.HeightType = TableRowHeightType.Exactly
for col_index, header in enumerate(headers):
cell = header_row.Cells[col_index]
cell.CellFormat.BackColor = Color.get_Green()
cell.CellFormat.VerticalAlignment = VerticalAlignment.Middle
paragraph = cell.AddParagraph()
paragraph.Format.HorizontalAlignment = HorizontalAlignment.Center
text_range = paragraph.AppendText(header)
text_range.CharacterFormat.Bold = True
# 数据行
for row_index, member in enumerate(team):
data_row = table.Rows[row_index + 1]
data_row.Height = 20
data_row.HeightType = TableRowHeightType.Exactly
for col_index, key in enumerate(headers):
cell = data_row.Cells[col_index]
cell.CellFormat.VerticalAlignment = VerticalAlignment.Middle
paragraph = cell.AddParagraph()
paragraph.Format.HorizontalAlignment = HorizontalAlignment.Center
# 防御性取值:字段缺失时用 “—” 占位
paragraph.AppendText(str(member.get(key, "—")))
# --- 7. 保存 ---
document.SaveToFile("员工目录.docx", FileFormat.Docx)
document.Close()
print("已生成 员工目录.docx")
几个值得注意的实现细节:
ResetCells的行数要加一:表头本身占一行,写成len(team)会少一行。AppendText()返回TextRange:字符格式(加粗、字号、颜色)都从这个对象上设置;段落对齐、段后间距则走paragraph.Format。member.get(key, "—"):单条记录缺字段时不会抛异常,也不会破坏表格的列对齐。- 嵌套对象不强行塞进表格:
负责人只有三个字段,逐行标签比单行表格更易读。 - 中文键名直接作为表头:因为
团队中每个对象的键就是“姓名、职位、邮箱、办公地点”,headers取出后直接就是中文列标题。如果实际项目更习惯用英文键(如name、title),可以在渲染表格时加一个列名映射字典,把英文键翻译成中文表头,数据访问逻辑不变。
六、预期输出
打开 员工目录.docx,应当看到:
- 主标题:
星澜科技有限公司 — 研发部人员目录,使用 Heading 1 样式。 - 报告日期:
报告日期:2026年11月17日。 - 部门概览 小标题,下面是中文概览正文。
- 部门负责人 小标题,下面三行
姓名 / 职位 / 邮箱标签。 - 团队成员 小标题,下面是一张 6 行 4 列的表格:绿色表头(姓名、职位、邮箱、办公地点),5 条数据行居中显示,带边框、行高固定。

七、常见注意事项
-
免费版的容量上限。 该免费包单文档最多 500 个段落和 25 个表格,超出部分会被截断。这意味着单次转换适合 2–3 页的报告、中小规模台账或 API 数据快照。
-
列标题的假设。 示例用
team[0].keys()作为列标题,前提是数组内所有记录的字段一致。真实数据里经常出现某条记录缺字段、或多出字段的情况。更稳健的做法是先扫描全部记录,取键的并集作为列标题,再用record.get(key, "—")填充。代价是多一次遍历,但对脏数据的容忍度更高。 -
错误处理的最小骨架。 JSON 往往来自外部 API 或用户上传,
json.loads可能因非法输入抛出JSONDecodeError。围绕转换逻辑包一层try/except,记录出错位置,比让脚本中途崩溃更容易排查:
try:
data = json.loads(raw_json)
convert(data)
except json.JSONDecodeError as e:
print(f"JSON 解析失败,位置 {e.pos}:{e.msg}")
-
编码与文件路径。 读取 JSON 文件时显式指定
encoding='utf-8';保存时第二个参数写明FileFormat.Docx。如果输出路径包含非 ASCII 字符,用pathlib解析成绝对路径再传入,可以避开一些平台差异。 -
渲染策略的选择。 同一个 JSON 可以渲染出完全不同的文档。扁平对象适合键值段落,记录集合适合表格,嵌套结构适合递归的小标题层级。混合结构可以分段处理:元信息用段落,
团队用表格,负责人用标签行——这正是上面示例的做法。
八、小结
JSON 转 Word 的核心不在于调用了哪个库的哪个方法,而在于先为数据结构建立清晰的映射契约:哪些字段进标题,哪些进段落,哪些进表格,嵌套层级如何用缩进和字号表达。Free Spire.Doc for Python 提供了一套与 Word 对象模型对齐的 API,把字符格式和段落格式两层控制暴露出来,让这种映射可以在代码里精确落地。在免费版的容量边界内,它足以覆盖报告生成、数据快照和结构化台账这类常见场景;超出边界时,分片或换用其他库都是合理的工程选择。
转载自 CSDN-专业IT技术社区
原文链接:https://blog.csdn.net/Eiceblue/article/details/171040402




