JSON 是应用程序、API 和数据库之间交换结构化数据最常用的格式之一。然而在许多业务场景中，JSON 数据需要被转化为可读的 Word 文档，例如报告、发票、摘要、合同或导出记录。

将 JSON 转换为 Word 并非简单的文件格式转换。JSON 本身不具备 Word 文档结构，因此需要先解析 JSON 数据，再将其元素映射到合适的 Word 文档组件，如段落、表格和标题。

本文将演示如何使用 Spire.Doc for Python 在 Python 中将 JSON 数据转换为 Word 文档。我们将介绍多种方法，包括将 JSON 导出为格式化文本、从 JSON 数组创建 Word 表格，以及从嵌套 JSON 数据生成结构化报告。

内容概览

1. 理解 JSON 转 Word 的原理
2. 安装 Spire.Doc for Python
3. 方法一：将 JSON 转换为格式化文本
4. 方法二：将 JSON 数组转换为 Word 表格
5. 方法三：从 JSON 生成结构化 Word 报告
6. 处理嵌套 JSON 对象
7. 处理缺失或可选字段
8. 将 JSON 文件转换为 Word 文档
9. 为什么选择 Spire.Doc 进行 JSON 转 Word
10. 常见问题
11. 总结

1. 理解 JSON 转 Word 的原理

JSON 和 Word 文档的用途截然不同。JSON 是一种用于数据交换和机器处理的结构化数据格式，而 Word 文档则面向人类阅读，具有丰富的格式、视觉层次和页面布局。

因此，将 JSON 转换为 Word 并非直接的格式转换，而是需要先解析 JSON 数据，再将其映射到合适的文档元素，然后才能生成 Word 文档。

转换过程通常遵循以下流程：

JSON 数据
      ↓
解析 JSON（json.loads）
      ↓
映射数据结构
      ↓
Spire.Doc for Python
      ↓
段落 / 表格 / 标题
      ↓
DOCX 文档

在 Python 中，通常使用内置的 json 模块解析 JSON 数据，由 Spire.Doc for Python 负责文档生成。分析并映射 JSON 结构后，Spire.Doc 可以通过编程方式创建段落、表格、标题、图片等 Word 元素，从而生成格式完整的 DOCX 文档。

下表展示了 JSON 结构与 Word 元素之间的常见映射关系：

理解这些映射关系非常重要，因为同样的 JSON 数据可以根据文档用途以不同方式呈现。例如，简单的键值对数据可以导出为段落，而记录集合通常以表格形式展示更便于阅读。借助 Spire.Doc for Python，可以通过编程实现这些映射，从结构化 JSON 数据生成专业的 Word 文档。

2. 安装 Spire.Doc for Python

在将 JSON 转换为 Word 之前，需要先在开发环境中安装 Spire.Doc for Python。

通过 pip 安装（推荐）

pip install spire.doc

也可以下载 Spire.Doc for Python并手动集成。

安装完成后，在项目中导入该库：

from spire.doc import *
from spire.doc.common import *

3. 方法一：将 JSON 转换为格式化文本

这是将 JSON 转换为 Word 最简单的方法，适用于 API 响应、配置文件和简单的 JSON 导出场景，其中每个键值对映射为一个段落。

示例 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()

输出结果

以下 Word 文档展示了 JSON 键值对如何被转换为格式化段落。

适用场景

此方法最适合以下情况：

• 简单的键值对 JSON 对象
• API 响应导出
• 配置文件文档化
• 快速数据快照

此方法不适用于大型数据集或表格数据，此时方法二（表格）的可读性更好。

如果你需要分析、筛选或操作电子表格中的结构化 JSON 数据，也可以参考我们的在 Python 中将 JSON 转换为 Excel指南。

4. 方法二：将 JSON 数组转换为 Word 表格

当 JSON 数据包含对象数组时，表格是在 Word 文档中展示数据最有效的方式。这是将 JSON 转换为 Word 最常见的场景，因为许多 API 和数据库都以 JSON 数组的形式返回数据。

示例 JSON

[
  {"产品": "笔记本电脑", "单价": 6999, "库存": 45},
  {"产品": "无线鼠标", "单价": 199, "库存": 200},
  {"产品": "机械键盘", "单价": 549, "库存": 120}
]

Python 代码

import json
from spire.doc import (
    Document, FileFormat, HorizontalAlignment,
    VerticalAlignment, TableRowHeightType, Color
)

json_data = '''[
  {"产品": "笔记本电脑", "单价": 6999, "库存": 45},
  {"产品": "无线鼠标", "单价": 199, "库存": 200},
  {"产品": "机械键盘", "单价": 549, "库存": 120}
]'''
data = json.loads(json_data)

document = Document()
section = document.AddSection()

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

document.SaveToFile("json_to_table.docx", FileFormat.Docx)
document.Close()

输出结果

以下截图展示了从 JSON 数组生成的 Word 表格。

为什么使用表格展示 JSON 数组

表格是 JSON 数组数据的天然呈现方式，原因如下：

• 每个 JSON 对象映射为表格的一行
• 每个键映射为列标题
• 数据对齐排列，便于浏览和比较
• 表格是报告、库存清单和数据库导出记录的标准格式

通过格式化增强 JSON 表格

与纯文本导出不同，Spire.Doc 可以将 JSON 数据渲染为专业格式的 Word 表格。除了基本的表格创建，还可以应用：

• 表格样式 – 使用 DefaultTableStyle 或 ApplyStyle 实现统一、精致的表格外观
• 边框和底纹 – 控制单元格边框、背景色和交替行颜色
• 对齐方式 – 在单元格、行或表格级别设置水平和垂直对齐
• 自定义格式 – 对单个单元格或区域应用字号、加粗和颜色
• 自动调整 – 使用 AutoFit 根据内容或窗口大小调整列宽

这些格式化能力可以将原始 JSON 数据转化为专业的报告布局，适用于商业文档、客户交付物和自动化报告流程。

如果需要创建更复杂的 Word 表格，例如合并单元格、自定义表格布局或高级格式化，请参阅我们的使用 Python 在 Word 文档中创建和格式化表格指南。

5. 方法三：从 JSON 生成结构化 Word 报告

实际业务中的 JSON 数据通常包含元数据、摘要文本和表格数据的混合。此方法结合标题、段落和表格，从 JSON 生成完整的结构化 Word 报告。

示例 JSON

{
  "title": "月度销售报告",
  "period": "2026年6月",
  "summary": "本月总营收达到580万元，较上期增长12%。所有区域均呈现正向增长。",
  "sales": [
    {"区域": "华北", "营收": 1500000, "销量": 320},
    {"区域": "华南", "营收": 1200000, "销量": 280},
    {"区域": "华东", "营收": 1800000, "销量": 410},
    {"区域": "西部", "营收": 1300000, "销量": 290}
  ]
}

Python 代码

import json
from spire.doc import (
    Document, FileFormat, HorizontalAlignment,
    VerticalAlignment, TableRowHeightType, Color,
    BuiltinStyle
)

json_data = '''{
  "title": "月度销售报告",
  "period": "2026年6月",
  "summary": "本月总营收达到580万元，较上期增长12%。所有区域均呈现正向增长。",
  "sales": [
    {"区域": "华北", "营收": 1500000, "销量": 320},
    {"区域": "华南", "营收": 1200000, "销量": 280},
    {"区域": "华东", "营收": 1800000, "销量": 410},
    {"区域": "西部", "营收": 1300000, "销量": 290}
  ]
}'''
data = json.loads(json_data)

document = Document()
section = document.AddSection()

heading_style = document.AddStyle(BuiltinStyle.Heading1)
subheading_style = document.AddStyle(BuiltinStyle.Heading2)

title_para = section.AddParagraph()
title_para.ApplyStyle(heading_style.Name)
title_para.AppendText(data.get("title", "报告"))

period_para = section.AddParagraph()
period_para.AppendText(f"报告期：{data.get('period', '无')}")
period_para.Format.AfterSpacing = 12

summary_heading = section.AddParagraph()
summary_heading.ApplyStyle(subheading_style.Name)
summary_heading.AppendText("摘要概述")

summary_para = section.AddParagraph()
summary_para.AppendText(data.get("summary", ""))
summary_para.Format.AfterSpacing = 12

sales_heading = section.AddParagraph()
sales_heading.ApplyStyle(subheading_style.Name)
sales_heading.AppendText("销售数据")

sales = data.get("sales", [])
if sales:
    headers = list(sales[0].keys())
    table = section.AddTable(True)
    table.ResetCells(len(sales) + 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

    for row_index, record in enumerate(sales):
        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
            paragraph.AppendText(str(record.get(key, "")))

document.SaveToFile("json_report.docx", FileFormat.Docx)
document.Close()

输出结果

生成的 Word 文档将标题、描述性文本和表格数据组合为结构化报告，使 JSON 数据更易于阅读和分享。

关键技术

本示例演示了从 JSON 生成 Word 报告的几项重要技术：

• 标题 – 使用 BuiltinStyle.Heading1 和 Heading2 构建文档结构，并兼容目录生成
• 段落 – 在标题之间添加摘要和描述性文本
• 表格 – 将 JSON 数组渲染为报告中的表格数据
• 组合使用 – 在同一文档中混合使用多种 Word 元素类型

结构化报告的重要性

在企业环境中，JSON 数据很少孤立存在。它通常来自 API、数据库或报表系统，需要被转化为决策者可以阅读、分享和归档的文档。常见场景包括：

• 销售报告 – 来自 CRM 或 ERP 系统的营收、销量和区域明细
• 库存报告 – 库存水平、补货预警和仓库汇总
• 客户摘要 – 联系信息、订单历史和账户状态
• 合规报告 – 审计日志、访问记录和策略状态
• 自动化报表系统 – 定时任务从 JSON 数据生成文档，并通过邮件或文档管理系统分发

Spire.Doc 能够将结构化 JSON 数据自动转化为精美的商业文档，在单一输出中组合标题、段落和表格。

如果需要构建更复杂的文档布局，例如多节报告、封面页、目录、页眉页脚或自定义文档模板，请参阅我们的使用 Python 创建结构化 Word 文档指南。

6. 处理嵌套 JSON 对象

许多实际场景中的 JSON 响应包含嵌套对象。例如，客户记录可能包含一个地址对象，其中又包含自己的字段。正确处理这些嵌套结构对于完整的 JSON 转 Word 转换至关重要。

示例 JSON

{
  "客户": {
    "姓名": "李明",
    "邮箱": "liming@ example.com",
    "地址": {
      "街道": "中关村大街1号",
      "城市": "北京",
      "省份": "北京市"
    }
  }
}

Python 代码

import json
from spire.doc import Document, FileFormat, HorizontalAlignment

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

json_data = '''{
  "客户": {
    "姓名": "李明",
    "邮箱": "liming@ example.com",
    "地址": {
      "街道": "中关村大街1号",
      "城市": "北京",
      "省份": "北京市"
    }
  }
}'''
data = json.loads(json_data)

document = Document()
section = document.AddSection()

add_nested_object(section, data)

document.SaveToFile("json_nested.docx", FileFormat.Docx)
document.Close()

输出结果

以下截图展示了从嵌套 JSON 结构生成的层次化 Word 文档。

嵌套 JSON 对象可以在 Word 文档中表示为层次化的节，使复杂数据结构更易于阅读和导航。

实现原理

add_nested_object 函数递归遍历 JSON 结构：

• 遇到字典值时，为该键创建加粗标题，并递归进入嵌套对象
• 遇到标量值时，创建包含键值对的段落
• indent_level 参数控制缩进和字号，以创建视觉层次

这种递归方式可以处理任意深度的嵌套，并在 Word 文档中生成可读的层次化布局。

7. 处理缺失或可选 JSON 字段

在实际应用中，来自 API 和数据库的 JSON 数据通常包含缺失或可选字段。不同记录的键可能不一致，某些字段可能完全缺失。妥善处理这些情况可以避免错误，并确保生成的 Word 文档完整无误。

含缺失字段的示例 JSON

[
  {"姓名": "李明", "邮箱": "liming@ example.com", "电话": "138-0100-1000"},
  {"姓名": "王芳", "邮箱": "wangfang@ example.com"},
  {"姓名": "赵强", "电话": "139-0300-3000"}
]

Python 代码

import json
from spire.doc import (
    Document, FileFormat, HorizontalAlignment,
    VerticalAlignment, TableRowHeightType, Color
)

json_data = '''[
  {"姓名": "李明", "邮箱": "liming@ example.com", "电话": "138-0100-1000"},
  {"姓名": "王芳", "邮箱": "wangfang@ example.com"},
  {"姓名": "赵强", "电话": "139-0300-3000"}
]'''
data = json.loads(json_data)

document = Document()
section = document.AddSection()

if data:
    all_keys = []
    for record in data:
        for key in record.keys():
            if key not in all_keys:
                all_keys.append(key)

    table = section.AddTable(True)
    table.ResetCells(len(data) + 1, len(all_keys))

    header_row = table.Rows[0]
    header_row.IsHeader = True
    header_row.Height = 20
    header_row.HeightType = TableRowHeightType.Exactly

    for col_index, header in enumerate(all_keys):
        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

    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(all_keys):
            data_row.Cells[col_index].CellFormat.VerticalAlignment = VerticalAlignment.Middle
            paragraph = data_row.Cells[col_index].AddParagraph()
            paragraph.Format.HorizontalAlignment = HorizontalAlignment.Center
            paragraph.AppendText(str(record.get(key, "无")))

document.SaveToFile("json_missing_fields.docx", FileFormat.Docx)
document.Close()

输出结果

以下截图展示了生成的 Word 表格，其中缺失字段自动填充了占位值，以保持文档结构的一致性。

关键技术

• dict.get(key, "无") – 当键缺失时返回默认值，避免 KeyError 异常
• 动态列收集 – 遍历所有记录以构建完整的列标题集合，确保不会遗漏仅出现在部分记录中的字段
• 一致的表格结构 – 所有行具有相同的列数，无论每条记录中存在哪些字段

这种方法在生产环境中必不可少，因为 API 响应的结构可能在不同记录或不同时间点存在差异。

8. 将 JSON 文件转换为 Word 文档

在实际应用中，JSON 数据通常来源于文件而非内联字符串。API 导出结果、配置文件、数据库转储、数据交换文件和日志数据通常都以 .json 文件的形式存储，需要被转换为 Word 文档。

JSON 文件的转换过程遵循以下流程：

JSON 文件（.json）
        ↓
加载 JSON（json.load）
        ↓
生成 Word 文档（Spire.Doc）
        ↓
DOCX 文档

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()

要点

• json.load() 直接读取并解析 JSON 文件，而 json.loads() 解析的是字符串
• encoding="utf-8" 确保 JSON 文件中的非 ASCII 字符能够正确处理
• JSON 文件加载为 Python 字典或列表后，可以使用本文前面介绍的任意方法，通过 Spire.Doc for Python 生成段落、表格或结构化报告

关于处理已加载数据的完整示例，可参考方法一（格式化文本）、方法二（表格）或方法三（结构化报告）。

9. 为什么选择 Spire.Doc 进行 JSON 转 Word

将 JSON 转换为 Word 涉及多项实际挑战，远不止简单的数据解析。生成格式正确的表格、应用一致的样式、创建包含标题和段落的结构化报告，以及处理嵌套或不完整的数据，都需要功能强大的文档生成 API。

JSON 转 Word 的挑战

• 表格生成 – JSON 数组必须映射为包含标题、行和单元格格式的 Word 表格
• 文档格式化 – 原始数据导出缺乏使 Word 文档可读的视觉层次
• 结构化报告 – 在同一文档中组合标题、段落和表格需要协调多种元素类型
• 嵌套数据 – 深层嵌套的 JSON 对象需要递归遍历和层次化布局
• 大型文档 – 从大型 JSON 数据集生成多页报告需要高效的资源管理

Spire.Doc for Python 的优势

Spire.Doc for Python 通过简洁的 API 解决了上述挑战：

• 无需安装 Microsoft Word 即可创建 Word 文档 – 无需 Office 安装或 Interop 依赖
• 生成段落、表格、图片、页眉和页脚 – 全面覆盖 Word 文档元素
• 应用内置和自定义样式 – 使用 BuiltinStyle 和 ParagraphStyle 实现跨文档的一致格式
• 自动化报告生成 – 以编程方式从任意 JSON 数据源构建结构化报告
• 导出为 DOCX 及其他格式 – 使用 FileFormat 保存为 DOCX、PDF、HTML、RTF 等

借助 Spire.Doc，JSON 转 Word 的过程变成了从解析数据到 Word 元素的结构化映射，而非手动字符串格式化或模板操作。

10. 常见问题

如何在 Python 中将 JSON 转换为 Word？

使用 Python 内置的 json 模块解析 JSON 数据，然后使用 Spire.Doc for Python 创建 Word 文档。将 JSON 键值对映射为段落，JSON 数组映射为表格，使用标题构建结构。基础示例参见方法一，完整报告参见方法三。

JSON 数组可以转换为 Word 表格吗？

可以。JSON 对象数组天然映射为 Word 表格，其中每个对象成为一行，每个键成为一列。完整代码示例参见方法二。

如何从 API 的 JSON 响应创建 DOCX 报告？

获取 API 响应的 JSON 数据，解析后使用 Spire.Doc for Python 生成报告。结合标题用于标题、段落用于摘要、表格用于数据数组。结构化报告示例参见方法三。

嵌套 JSON 对象可以导出到 Word 吗？

可以。使用递归函数遍历嵌套 JSON 对象，为对象键创建标题，为标量值创建段落。带有视觉层次的嵌套结构处理示例参见第6节。

如何将 JSON 文件转换为 Word 文档？

使用 Python 的 json.load() 读取 JSON 文件，然后使用 Spire.Doc for Python 处理解析后的数据。代码示例参见第8节。

从 JSON 数据生成 Word 文档的最佳方式是什么？

最佳方式取决于 JSON 结构。简单的键值对数据使用格式化段落；数组使用表格；包含混合内容的复杂嵌套数据则组合使用标题、段落和表格，如方法三所示。

11. 总结

从 JSON 数据生成 Word 文档是报表、文档自动化和数据导出工作流中的常见需求。借助 Spire.Doc for Python，可以直接从 JSON 创建段落、表格和结构化文档布局，从而更便捷地从应用数据生成专业的 DOCX 文件。

同样的方法可以扩展到 API 响应、数据库记录、配置文件和其他结构化数据源，帮助在小型项目和企业系统中实现文档生成的自动化。

对于涉及大型文档或文档转换需求的场景，需要授权版本。