JSON 是接口和配置文件里最常见的结构化数据格式,而 Word 文档是业务人员阅读、批注和归档信息的载体。把 JSON 数据导出成结构清晰的 Word 文档,是报表自动化、接口数据快照这类场景中的常见需求。本文按"扁平对象、对象数组、嵌套结构"由简到繁的顺序,梳理从 JSON 到 Word 的结构映射思路与代码实现,并补上文件读取与文档保存的完整流程,重点放在映射策略和几个容易踩坑的细节上。
环境准备与对象模型
本文使用 Spire.Doc 这个 Python 库来生成 DOCX 文件,它不依赖本机安装 Microsoft Word。安装方式:
bash
pip install Spire.Doc
使用前有两点需要了解。
- 第一,该库的免费版本对单个文档有段落和表格数量上限,超出部分会被截断而不是抛出异常,因此在数据量较大时最好提前估算或主动拆分成多个文档。
- 第二,其对象层级可以概括为一条链:
Document→Section→Paragraph→TextRange。Document是文档根对象,Section承载页面级设置,Paragraph是段落容器,TextRange控制段落中一段连续文本的格式,如字体、字号、加粗。表格通过Section.AddTable添加,单元格内部同样走段落与文本范围的格式控制;表格行用TableRowHeightType这类枚举控制行高策略,单元格用CellFormat控制垂直对齐与底纹。
JSON 到 Word 的映射原则
JSON 转 Word 不是格式转换,而是一次结构映射:键值对、数组、嵌套对象要被翻译成段落、表格、标题这些人类可读的组件。动手写代码之前先把映射规则定下来,比边写边调更省事。常见对应关系如下:
| JSON 结构 | Word 元素 | 典型场景 |
|---|---|---|
| 扁平对象的键值对 | 段落(键: 值) | 配置说明、个人卡片、接口快照 |
| 对象数组 | 表格(键→列标题,对象→行) | 员工列表、订单、库存 |
| 嵌套对象 | 标题 + 缩进段落(递归) | 结构化报告、层级摘要 |
场景一:扁平对象转为格式化文本
最简单的映射:JSON 对象的每个键值对生成一个独立段落。
python
import json
from spire.doc import Document, FileFormat, HorizontalAlignment
json_data = '{"项目": "数据管道", "负责人": "张伟", "状态": "进行中"}'
data = json.loads(json_data)
document = Document()
section = document.AddSection()
for key, value in data.items():
paragraph = section.AddParagraph()
text_range = paragraph.AppendText(f"{key}: {value}")
text_range.CharacterFormat.FontSize = 12
paragraph.Format.AfterSpacing = 6
document.SaveToFile("json_to_text.docx", FileFormat.Docx)
document.Close()
AppendText 返回 TextRange 对象,字符级格式通过它设置;段落级间距和对齐通过 paragraph.Format 控制。这套格式控制方式在后面的表格单元格里同样适用。
场景二:对象数组转为 Word 表格
对象数组天然对应表格:每个对象一行,对象的键集合决定列标题。下面这段代码以首条记录的键作为表头,并处理了表头底纹、垂直居中和行高精确控制:
python
if data:
headers = list(data[0].keys())
table = section.AddTable(True)
table.ResetCells(len(data) + 1, len(headers))
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):
header_row.Cells[col_index].CellFormat.Shading.BackgroundPatternColor = Color.get_Gray()
header_row.Cells[col_index].CellFormat.VerticalAlignment = VerticalAlignment.Middle
paragraph = header_row.Cells[col_index].AddParagraph()
paragraph.Format.HorizontalAlignment = HorizontalAlignment.Center
text_range = paragraph.AppendText(header)
text_range.CharacterFormat.Bold = True
text_range.CharacterFormat.FontSize = 12
for row_index, record in enumerate(data):
data_row = table.Rows[row_index + 1]
data_row.Height = 20
data_row.HeightType = TableRowHeightType.Exactly
for col_index, key in enumerate(headers):
data_row.Cells[col_index].CellFormat.VerticalAlignment = VerticalAlignment.Middle
paragraph = data_row.Cells[col_index].AddParagraph()
paragraph.Format.HorizontalAlignment = HorizontalAlignment.Center
text_range = paragraph.AppendText(str(record.get(key, "")))
text_range.CharacterFormat.FontSize = 11
有几个细节值得注意。record.get(key, "") 是必要的:即便表头取自首条记录,后续记录也可能缺字段,用 get 取默认空串能避免 KeyError 中断整批转换。IsHeader = True 让表头跨页时重复显示,HeightType = TableRowHeightType.Exactly 保证行高固定、表格观感整齐。另外,以首条记录取表头的做法在字段差异较大时会失真,更稳妥的做法是先扫描全部记录取键的并集,或预先定义固定列清单只输出关心的字段。
场景三:嵌套 JSON 的递归渲染
真实数据里嵌套很常见,客户记录里往往嵌着地址对象,订单里嵌着商品明细。递归函数的思路是按值的类型分流:值是字典就生成加粗标题再递归深入,值是标量就生成键值段落并按层级缩进。
python
def add_nested_object(section, obj, indent_level=0):
for key, value in obj.items():
if isinstance(value, dict):
heading_para = section.AddParagraph()
heading_text = " " * indent_level + key.capitalize()
text_range = heading_para.AppendText(heading_text)
text_range.CharacterFormat.Bold = True
text_range.CharacterFormat.FontSize = 12 - indent_level
heading_para.Format.AfterSpacing = 4
add_nested_object(section, value, indent_level + 1)
else:
paragraph = section.AddParagraph()
label = " " * indent_level + f"{key}: {value}"
text_range = paragraph.AppendText(label)
text_range.CharacterFormat.FontSize = 11
paragraph.Format.AfterSpacing = 2
这个递归能处理任意深度,缩进层级加字号递减共同构成视觉层次。两个边界情况要留意:键名为英文时 capitalize() 会改变大小写,需保留原始键名就去掉该调用;12 - indent_level 在嵌套很深时可能得到过小甚至非正的字号,实际使用应设下限或改为按层级固定字号档位。
从 JSON 文件读取并生成文档
实际项目里数据往往来自文件或接口响应,而不是硬编码字符串。完整流程是先读取解析,再套用上面任一渲染方式,最后保存:
python
import json
from spire.doc import Document, FileFormat
with open("data.json", "r", encoding="utf-8") as f:
data = json.load(f)
document = Document()
section = document.AddSection()
# 用上面三种方式中的任意一种处理已加载的 JSON 数据
document.SaveToFile("data_report.docx", FileFormat.Docx)
document.Close()
读取时显式写 encoding="utf-8",能避免中文字段在部分平台默认编码下乱码。数据来自 HTTP 接口的话,把 json.load(f) 换成 response.json() 即可,后续渲染逻辑完全复用。
实践中的几点考量
容量限制要提前预判。 数据行数多、每条记录又生成多个段落时,段落数容易越界,而超限是静默截断而非报错。提前计数或按数据量拆分为多个文档,是更稳妥的处理。
列键不一致的处理策略。 首条记录取表头简洁直观,记录多、字段差异大时列数会失真。取键的并集能保全字段但列数可能膨胀,固定列清单可控但会丢字段。选哪种取决于文档用途:面向人阅读的报告宜控制列数,面向数据备查的快照可以保留全部字段。
格式与内容分离。 代码里 CharacterFormat 和 Format 的调用很密集,散落在遍历逻辑中以后调样式会很痛苦。把样式设置抽成辅助函数,在生成段落或单元格时统一应用,是值得采用的代码组织方式。
JSON 转 Word 没有唯一正确的实现,映射策略取决于数据结构和用途。先想清楚"谁看这份文档、关心哪些字段",再决定用段落、表格还是递归层级来组织输出,比追求一个通用转换器更务实。文中这个库的文档对象接口粒度较细,需要精确控制格式时比较灵活,同时也要求开发者对输出文档的最终形态有清晰预设。