查看: 507|回复: 3

Python用Spire.Doc把JSON转Word的三种映射实现

[复制链接]
发表于 5 小时前 | 显示全部楼层 |阅读模式
JSON 常出现在接口响应和配置文件中,Word 则用于业务阅读、批注和归档。把 JSON 导出为结构清晰的 DOCX,是报表自动化、接口数据快照等脚本任务中的常见需求。本文使用 Spire.Doc 这个 Python 库来生成文档,它不依赖本机安装 Microsoft Word,重点放在结构映射思路、代码实现和容易踩坑的细节上。

环境准备与对象模型

安装命令如下:
  1. pip install Spire.Doc
复制代码

使用前需要了解两点。第一,该库免费版本对单个文档有段落和表格数量上限,超出部分会被截断,而不是抛出异常;数据量较大时应提前估算或主动拆分为多个文档。第二,对象层级可以概括为一条链:Document → Section → Paragraph → TextRange。Document 是文档根对象,Section 承载页面级设置,Paragraph 是段落容器,TextRange 控制段落中一段连续文本的格式,例如字体、字号、加粗。表格通过 Section.AddTable 添加,单元格内部同样走段落与文本范围的格式控制;表格行可用 TableRowHeightType 这类枚举控制行高策略,单元格可用 CellFormat 控制垂直对齐与底纹。

JSON 到 Word 的映射原则

JSON 转 Word 不是简单的格式转换,而是一次结构映射:键值对、数组、嵌套对象要被翻译成段落、表格、标题这些人类可读的组件。动手写代码之前先把映射规则定下来,比边写边调更省事。常见对应关系是:扁平对象的键值对映射为段落,适合配置说明、个人卡片、接口快照;对象数组映射为表格,键作为列标题、对象作为行,适合员工列表、订单、库存;嵌套对象映射为标题加缩进段落,通过递归渲染,适合结构化报告和层级摘要。

场景一:扁平对象转为格式化文本

最简单的映射是 JSON 对象的每个键值对生成一个独立段落。示例先把 JSON 字符串解析为字典,再创建文档和节,最后逐项追加段落并设置字符格式与段后间距:
  1. import json
  2. from spire.doc import Document, FileFormat, HorizontalAlignment
  3. json_data = '{"项目": "数据管道", "负责人": "张伟", "状态": "进行中"}'
  4. data = json.loads(json_data)
  5. document = Document()
  6. section = document.AddSection()
  7. for key, value in data.items():
  8.     paragraph = section.AddParagraph()
  9.     text_range = paragraph.AppendText(f"{key}: {value}")
  10.     text_range.CharacterFormat.FontSize = 12
  11.     paragraph.Format.AfterSpacing = 6
  12. document.SaveToFile("json_to_text.docx", FileFormat.Docx)
  13. document.Close()
复制代码

AppendText 返回 TextRange 对象,字符级格式通过它设置;段落级间距和对齐通过 paragraph.Format 控制。这套格式控制方式在后面的表格单元格里同样适用。

场景二:对象数组转为 Word 表格

对象数组天然对应表格:每个对象一行,对象的键集合决定列标题。下面这段代码承接前面创建的 section 与已加载的 data 列表,以首条记录的键作为表头,并处理表头底纹、垂直居中和行高精确控制:
  1. if data:
  2.     headers = list(data[0].keys())
  3.     table = section.AddTable(True)
  4.     table.ResetCells(len(data) + 1, len(headers))
  5.     header_row = table.Rows[0]
  6.     header_row.IsHeader = True
  7.     header_row.Height = 20
  8.     header_row.HeightType = TableRowHeightType.Exactly
  9.     for col_index, header in enumerate(headers):
  10.         header_row.Cells[col_index].CellFormat.Shading.BackgroundPatternColor = Color.get_Gray()
  11.         header_row.Cells[col_index].CellFormat.VerticalAlignment = VerticalAlignment.Middle
  12.         paragraph = header_row.Cells[col_index].AddParagraph()
  13.         paragraph.Format.HorizontalAlignment = HorizontalAlignment.Center
  14.         text_range = paragraph.AppendText(header)
  15.         text_range.CharacterFormat.Bold = True
  16.         text_range.CharacterFormat.FontSize = 12
  17.     for row_index, record in enumerate(data):
  18.         data_row = table.Rows[row_index + 1]
  19.         data_row.Height = 20
  20.         data_row.HeightType = TableRowHeightType.Exactly
  21.         for col_index, key in enumerate(headers):
  22.             data_row.Cells[col_index].CellFormat.VerticalAlignment = VerticalAlignment.Middle
  23.             paragraph = data_row.Cells[col_index].AddParagraph()
  24.             paragraph.Format.HorizontalAlignment = HorizontalAlignment.Center
  25.             text_range = paragraph.AppendText(str(record.get(key, "")))
  26.             text_range.CharacterFormat.FontSize = 11
复制代码

有几个细节值得注意。record.get(key, "") 是必要的:即便表头取自首条记录,后续记录也可能缺字段,用 get 取默认空串能避免 KeyError 中断整批转换。IsHeader = True 让表头跨页时重复显示,HeightType = TableRowHeightType.Exactly 保证行高固定、表格观感整齐。另外,以首条记录取表头的做法在字段差异较大时会失真,更稳妥的做法是先扫描全部记录取键的并集,或预先定义固定列清单只输出关心的字段。

场景三:嵌套 JSON 的递归渲染

真实数据里嵌套很常见,客户记录里往往嵌着地址对象,订单里嵌着商品明细。递归函数的思路是按值的类型分流:值是字典就生成加粗标题再递归深入,值是标量就生成键值段落并按层级缩进。示例函数可直接接收 section 和待渲染对象:
  1. def add_nested_object(section, obj, indent_level=0):
  2.     for key, value in obj.items():
  3.         if isinstance(value, dict):
  4.             heading_para = section.AddParagraph()
  5.             heading_text = " " * indent_level + key.capitalize()
  6.             text_range = heading_para.AppendText(heading_text)
  7.             text_range.CharacterFormat.Bold = True
  8.             text_range.CharacterFormat.FontSize = 12 - indent_level
  9.             heading_para.Format.AfterSpacing = 4
  10.             add_nested_object(section, value, indent_level + 1)
  11.         else:
  12.             paragraph = section.AddParagraph()
  13.             label = " " * indent_level + f"{key}: {value}"
  14.             text_range = paragraph.AppendText(label)
  15.             text_range.CharacterFormat.FontSize = 11
  16.             paragraph.Format.AfterSpacing = 2
复制代码

这个递归能处理任意深度,缩进层级加字号递减共同构成视觉层次。两个边界情况要留意:键名为英文时 capitalize() 会改变大小写,需保留原始键名就去掉该调用;12 - indent_level 在嵌套很深时可能得到过小甚至非正的字号,实际使用应设下限或改为按层级固定字号档位。

从 JSON 文件读取并生成文档

实际项目里数据往往来自文件或接口响应,而不是硬编码字符串。完整流程是先读取解析,再套用上面任一渲染方式,最后保存:
  1. import json
  2. from spire.doc import Document, FileFormat
  3. with open("data.json", "r", encoding="utf-8") as f:
  4.     data = json.load(f)
  5. document = Document()
  6. section = document.AddSection()
  7. # 用上面三种方式中的任意一种处理已加载的 JSON 数据
  8. document.SaveToFile("data_report.docx", FileFormat.Docx)
  9. document.Close()
复制代码

读取时显式写 encoding="utf-8",能避免中文字段在部分平台默认编码下乱码。数据来自 HTTP 接口的话,把 json.load(f) 换成 response.json() 即可,后续渲染逻辑完全复用。

实践中的几点考量

容量限制要提前预判。数据行数多、每条记录又生成多个段落时,段落数容易越界,而超限是静默截断而非报错。提前计数或按数据量拆分为多个文档,是更稳妥的处理。

列键不一致的处理策略。首条记录取表头简洁直观,记录多、字段差异大时列数会失真。取键的并集能保全字段但列数可能膨胀,固定列清单可控但会丢字段。选哪种取决于文档用途:面向人阅读的报告宜控制列数,面向数据备查的快照可以保留全部字段。

格式与内容分离。代码里 CharacterFormat 和 Format 的调用很密集,散落在遍历逻辑中以后调样式会很痛苦。把样式设置抽成辅助函数,在生成段落或单元格时统一应用,是值得采用的代码组织方式。

JSON 转 Word 没有唯一正确的实现,映射策略取决于数据结构和用途。先想清楚谁看这份文档、关心哪些字段,再决定用段落、表格还是递归层级来组织输出,比追求一个通用转换器更务实。Spire.Doc 的文档对象接口粒度较细,需要精确控制格式时比较灵活,同时也要求开发者对输出文档的最终形态有清晰预设。
回复

使用道具 举报

发表于 5 小时前 | 显示全部楼层

Re: Python用Spire.Doc把JSON转Word的三种映射实现

楼主的三种映射思路很清晰,扁平对象走段落、对象数组走表格、嵌套对象走标题加缩进,这个划分对实际脚本很好落地。环境准备里提到免费版超限会静默截断而不是抛异常,这点很关键,数据量大时确实容易埋坑。 代码细节上,AppendText 返回 TextRange、单元格里继续用段落格式控制,这条链讲得明白;表头 IsHeader、行高 Exactly、底纹和垂直居中也很适合报表场景。不过场景二的代码到 text 就截断了,后面如果补上相关 import 以及列宽、长文本换行处理会更完整。场景三嵌套对象的递归渲染也期待展开。整体很有参考价值。
回复 支持 反对

使用道具 举报

发表于 5 小时前 | 显示全部楼层

Re: Python用Spire.Doc把JSON转Word的三种映射实现

这篇把 JSON 到 DOCX 从“格式转换”拆成“结构映射”讲得很清楚,扁平对象走段落、对象数组走表格、嵌套对象用标题加缩进递归,这个分类很实用。两个细节提醒也很有价值:免费版超限是截断而不报错,批量脚本里最好先估算段落和表格数量;Document→Section→Paragraph→TextRange 这条对象链也把格式控制的位置说明白了。场景二的代码里用到了 Color、TableRowHeightType 和 VerticalAlignment,实际跑的时候记得从 spire.doc 导入;表头行设置 IsHeader 对跨页重复表头应该也有帮助。期待后续嵌套对象递归渲染和拆分文档的部分。
回复 支持 反对

使用道具 举报

发表于 5 小时前 | 显示全部楼层

Re: Python用Spire.Doc把JSON转Word的三种映射实现

这篇思路挺清楚,先定映射规则再写代码这点很实用。Spire.Doc 的 Document 到 Section、Paragraph、TextRange 的层级和表格格式控制讲得比较明白,扁平对象转段落、对象数组转表格这两个场景也容易落地。 提醒两个小点:场景二示例里用到了 Color、VerticalAlignment、TableRowHeightType,但开头只导入了 Document、FileFormat、HorizontalAlignment,实际跑之前要把这些补上;另外 JSON 示例里的 " 在论坛里看是转义,复制到本地时记得换成正常双引号。免费版段落和表格数量上限会被截断这个坑也值得强调,数据量大时最好先估算或拆文档。 嵌套对象的递归渲染目前只讲了原则,期待后续把标题层级和缩进段落的完整实现补上。整体作为编程脚本的入门示例已经挺有参考价值。
回复 支持 反对

使用道具 举报

您需要登录后才可以回帖 登录 | 注册

本版积分规则

指导单位

江苏省公安厅

江苏省通信管理局

浙江省台州刑侦支队

DEFCON GROUP 86025

Hacking Group 021A

旗下站点

态势感知中心

应急响应中心

红盟安全

联系我们

官方QQ群:112851260

官方邮箱:security#ihonker.org(#改成@)

官方核心成员

关注微信公众号

Archiver|手机版|小黑屋| ( 沪ICP备2021026908号 )

GMT+8, 2026-11-17 07:46 , Processed in 0.023825 second(s), 18 queries , Gzip On, Redis On.

Powered by ihonker.com

Copyright © 2015-现在.

  • 返回顶部