使用 Python 将 JSON 转换为 Word 文档的实践指南

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

相关推荐
卷无止境43 分钟前
AI 加速开发之后,如何应对尚未发现的代码安全威胁
后端·python
cpolar技术支持1 小时前
容器数是 6 个、6 个、还是 6 个,可服务早被换掉了:用一个 5.5MB 的 Go 单文件把机器每周的变化记下来,再给它套一层别人看不懂的入口
python·docker·ai·cpolar
ONEYAC唯样1 小时前
YXC扬兴科技小型化有源晶振OT4JI-111-24M,提升红外热成像稳定性
人工智能·python·pygame
威哥爱编程1 小时前
模拟面试智能体开发实战 09:把面试官装进手机,鸿蒙端聊天界面用 SSE 流式输出让回复逐字滚出来
python·agent·harmonyos
威哥爱编程2 小时前
模拟面试智能体开发实战 10:配置写死在代码里还怎么换服务端,把设置和简历做成界面可配、可存
python·agent·harmonyos
青少儿编程课堂2 小时前
第十八届蓝桥杯青少组图形化 + 全国青少年信息素养大赛 + 电子学会图形化考级:校园三消乐大挑战解析
c++·python·算法·bfs·信息学竞赛
青少儿编程课堂2 小时前
蓝桥杯·全国青少年信息素养大赛·电子学会Python/C++考级:网格连通块与岛屿数量(DFS+BFS双解)
c++·python·算法·bfs·信息学竞赛
M--Y12 小时前
LangGraph 工作流模式
开发语言·javascript·python·langchain·大模型·llm·langgraph
岁月宁静12 小时前
DeepSeek Harness 实战与架构解析:让 Agent 从“会聊”到“能交付”
人工智能·python·agent