JSON 常出现在接口响应和配置文件中,Word 则用于业务阅读、批注和归档。把 JSON 导出为结构清晰的 DOCX,是报表自动化、接口数据快照等脚本任务中的常见需求。本文使用 Spire.Doc 这个 Python 库来生成文档,它不依赖本机安装 Microsoft Word,重点放在结构映射思路、代码实现和容易踩坑的细节上。
环境准备与对象模型
安装命令如下:
使用前需要了解两点。第一,该库免费版本对单个文档有段落和表格数量上限,超出部分会被截断,而不是抛出异常;数据量较大时应提前估算或主动拆分为多个文档。第二,对象层级可以概括为一条链:Document → Section → Paragraph → TextRange。Document 是文档根对象,Section 承载页面级设置,Paragraph 是段落容器,TextRange 控制段落中一段连续文本的格式,例如字体、字号、加粗。表格通过 Section.AddTable 添加,单元格内部同样走段落与文本范围的格式控制;表格行可用 TableRowHeightType 这类枚举控制行高策略,单元格可用 CellFormat 控制垂直对齐与底纹。
JSON 到 Word 的映射原则
JSON 转 Word 不是简单的格式转换,而是一次结构映射:键值对、数组、嵌套对象要被翻译成段落、表格、标题这些人类可读的组件。动手写代码之前先把映射规则定下来,比边写边调更省事。常见对应关系是:扁平对象的键值对映射为段落,适合配置说明、个人卡片、接口快照;对象数组映射为表格,键作为列标题、对象作为行,适合员工列表、订单、库存;嵌套对象映射为标题加缩进段落,通过递归渲染,适合结构化报告和层级摘要。
场景一:扁平对象转为格式化文本
最简单的映射是 JSON 对象的每个键值对生成一个独立段落。示例先把 JSON 字符串解析为字典,再创建文档和节,最后逐项追加段落并设置字符格式与段后间距:
- 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 表格
对象数组天然对应表格:每个对象一行,对象的键集合决定列标题。下面这段代码承接前面创建的 section 与已加载的 data 列表,以首条记录的键作为表头,并处理表头底纹、垂直居中和行高精确控制:
- 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 的递归渲染
真实数据里嵌套很常见,客户记录里往往嵌着地址对象,订单里嵌着商品明细。递归函数的思路是按值的类型分流:值是字典就生成加粗标题再递归深入,值是标量就生成键值段落并按层级缩进。示例函数可直接接收 section 和待渲染对象:
- 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 文件读取并生成文档
实际项目里数据往往来自文件或接口响应,而不是硬编码字符串。完整流程是先读取解析,再套用上面任一渲染方式,最后保存:
- 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 没有唯一正确的实现,映射策略取决于数据结构和用途。先想清楚谁看这份文档、关心哪些字段,再决定用段落、表格还是递归层级来组织输出,比追求一个通用转换器更务实。Spire.Doc 的文档对象接口粒度较细,需要精确控制格式时比较灵活,同时也要求开发者对输出文档的最终形态有清晰预设。 |