将 Word 文档转换为 JSON 是构建自动化文档处理流水线、向 AI 模型输送内容，或将 DOCX 文件中的结构化数据迁移到数据库和 API 时的常见需求。与 CSV 或 XML 不同，JSON 是一种灵活的层级格式，可以在单一输出中表示段落、表格和嵌套的文档结构。

然而，Word 文件本身并不支持 JSON 导出。.docx 文件是由节、段落、样式和表格组成的富文本文档，而非结构化数据源。将其转换为 JSON 时，需要决定如何将内容映射为有意义的结构。

本教程演示如何使用 Spire.Doc for Python 在 Python 中将 Word 转换为 JSON。你将学习三种由浅入深的方法：提取纯段落文本、将 Word 表格转换为 JSON 数组，以及在层级化 JSON 输出中保留完整的文档结构（包括标题、段落和表格）。本教程中的示例同时适用于 Spire.Doc 支持的 DOCX 和旧版 DOC 文件。

快速导航

1. Word 是如何转换为 JSON 的？
2. 安装所需库
3. 方法一：将 Word 文本转换为 JSON
4. 方法二：将 Word 表格转换为 JSON
5. 方法三：在 JSON 中保留文档结构
6. Word 转 JSON 的适用场景
7. 局限性与最佳实践
8. 常见问题
9. 总结

1. Word 是如何转换为 JSON 的？

Word 文档是由节、段落和表格组成的富文本格式，而非结构化数据格式。将 Word 转换为 JSON 时，并没有统一的标准来规定内容的表示方式，合适的结构取决于 JSON 的用途：

例如，一个包含标题和段落的 Word 文档可以用 JSON 表示为：

{
  "document": [
    {"type": "heading", "level": 1, "text": "项目概述"},
    {"type": "paragraph", "text": "本报告汇总了季度业绩情况。"}
  ]
}

本教程的三种方法分别对应上述结构选择：

• 方法一 生成段落数组（适用于 AI 向量化、搜索索引）
• 方法二 生成表格行对象（适用于数据库导入、数据提取）
• 方法三 生成层级结构（适用于 RAG、知识库、文档理解）

选择与你的目标匹配的方法，也可以组合多种方法的元素来构建自定义结构。

2. 安装所需库

本教程使用 Spire.Doc for Python 来读取和解析 DOC/DOCX 文件。通过 pip 安装：

pip install spire.doc

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

安装完成后，在 Python 脚本中导入该库：

from spire.doc import Document, FileFormat
from spire.doc.common import *

Spire.Doc 提供了加载 Word 文档、遍历节/段落/表格以及提取文本内容等 API，足以构建完整的 Word 转 JSON 流水线。

3. 方法一：将 Word 文本转换为 JSON

将 Word 转换为 JSON 最简单的方式是提取文档中所有段落文本，存入 JSON 数组。当你只需要纯文本内容而不需要结构元数据时（例如全文搜索、AI 文本向量化或简单的内容导出），这种方式非常适用。

3.1 从 Word 文档中读取段落

Spire.Doc 将 Word 文档表示为 Section（节） 的集合，每个节包含若干 Paragraph（段落）。要提取所有文本，需要遍历每个节及其中的每个段落。

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

input_file = "项目报告.docx"

document = Document()
document.LoadFromFile(input_file)

paragraphs = []
for i in range(document.Sections.Count):
    section = document.Sections.get_Item(i)
    for j in range(section.Paragraphs.Count):
        paragraph = section.Paragraphs.get_Item(j)
        text = paragraph.Text
        if text.strip():
            paragraphs.append(text)

document.Close()

每个段落的 .Text 属性返回纯文本内容，不含格式信息。if text.strip() 检查用于过滤 Word 中作为间距或布局元素存在的空段落。

3.2 将提取的文本序列化为 JSON

假设上一步提取的段落数据存储在 paragraphs 列表中，可以将其序列化为 JSON 并保存到文件：

import json

output_file = "paragraphs.json"

result = {
    "source": input_file,
    "paragraph_count": len(paragraphs),
    "paragraphs": paragraphs
}

with open(output_file, "w", encoding="utf-8") as f:
    json.dump(result, f, indent=2, ensure_ascii=False)

输出示例

以下 JSON 片段展示了生成的输出文件结构：

{
  "source": "项目报告.docx",
  "paragraph_count": 3,
  "paragraphs": [
    "季度销售报告",
    "本文档概述了各区域的销售业绩情况。"
  ]
}

转换结果

下图展示了源 Word 文档和提取段落后生成的 JSON 文件。

3.3 说明

为什么要逐个遍历 Section 和 Paragraph，而不是一次性提取所有文本？因为 Word 文档是层级结构：一个文档包含一个或多个节（每个节有独立的页面布局），每个节又包含若干段落。在这一层级进行遍历，可以灵活控制要包含或跳过哪些内容，比如过滤空段落或仅提取特定节的内容。

将段落存储为 JSON 数组是最直接的结构。每个元素都是一个字符串，下游系统可以轻松消费。此方法适用于：

• 全文索引：将段落文本送入 Elasticsearch 等搜索引擎
• AI 文本向量化：将段落转换为向量表示，用于语义搜索
• 简单内容导出：从 Word 文件中提取可读文本，不含格式

不过，这种方法会丢失结构信息。标题、正文和列表项都会被同等对待。如果需要区分它们，请参见方法三。

如果只是想从 Word 文档中提取文本内容而无需转换为 JSON，也可以参考我们的在 Python 中从 Word 文档提取文本的指南。

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

在许多 Word 文档（报表、发票、产品清单、配置表）中，最有价值的内容往往在表格里，而非段落中。将 Word 表格转换为 JSON，可以提取结构化的行列数据，直接加载到数据库、API 或数据分析工具中。

为什么表格需要特殊处理

Word 中的表格以行和单元格的网格形式存储，每个单元格包含自己的段落。与段落文本不同，表格数据具有天然的二维结构，可以自然地映射为 JSON 对象。第一行通常是列标题，后续行是数据记录。

从 Word 文档中提取表格

以下代码读取 Word 文档中的所有表格，以第一行作为列标题，将每个后续行转换为一个 JSON 对象：

import json
from spire.doc import Document
from spire.doc.common import *

input_file = "销售数据.docx"
output_file = "tables.json"

document = Document()
document.LoadFromFile(input_file)

all_tables = []

for i in range(document.Sections.Count):
    section = document.Sections.get_Item(i)
    for t in range(section.Tables.Count):
        table = section.Tables.get_Item(t)
        rows_data = []

        if table.Rows.Count < 2:
            continue

        header_row = table.Rows[0]
        headers = []
        for c in range(header_row.Cells.Count):
            cell_text = header_row.Cells[c].Paragraphs[0].Text.strip()
            headers.append(cell_text)

        for r in range(1, table.Rows.Count):
            row = table.Rows[r]
            row_dict = {}
            for c in range(row.Cells.Count):
                cell_text = row.Cells[c].Paragraphs[0].Text.strip()
                row_dict[headers[c] if c < len(headers) else f"Column_{c}"] = cell_text
            rows_data.append(row_dict)

        all_tables.append({
            "table_index": t,
            "headers": headers,
            "row_count": len(rows_data),
            "rows": rows_data
        })

document.Close()

result = {
    "source": input_file,
    "table_count": len(all_tables),
    "tables": all_tables
}

with open(output_file, "w", encoding="utf-8") as f:
    json.dump(result, f, indent=2, ensure_ascii=False)

输出示例

以下 JSON 片段展示了生成的输出文件结构，每行表格数据以表头为键映射为 JSON 对象：

{
  "source": "销售数据.docx",
  "table_count": 1,
  "tables": [
    {
      "table_index": 0,
      "headers": ["区域", "产品", "销量", "营收"],
      "row_count": 3,
      "rows": [
        {"区域": "华北", "产品": "笔记本电脑", "销量": "120", "营收": "114000"},
        {"区域": "华南", "产品": "笔记本电脑", "销量": "80", "营收": "76000"}
      ]
    }
  ]
}

转换结果

下图展示了 Word 文档中的表格数据如何转换为结构化 JSON 记录。

说明

代码将第一行视为标题行，后续行中每个单元格的值映射到对应的标题键。这会生成一个 JSON 对象数组，是表格数据最常见也最实用的格式。

关键注意事项：

• table.Rows.Count < 2 跳过只有标题行或为空的表格
• row.Cells[c].Paragraphs[0].Text 提取每个单元格中第一段的文本。为简化示例，此处只读取第一段。如果单元格包含多个段落，需要遍历整个 Paragraphs 集合并拼接结果：

cell_text = "\n".join(
    row.Cells[c].Paragraphs[p].Text.strip()
    for p in range(row.Cells[c].Paragraphs.Count)
    if row.Cells[c].Paragraphs[p].Text.strip()
)

• headers[c] if c < len(headers) else f"Column_{c}" 处理数据行的单元格数多于标题行的情况

此方法非常适合从 Word 文档中的报表、发票、产品目录和配置表中提取结构化数据。生成的 JSON 可以直接加载到数据库、用于 Web API 或由数据分析工具处理。

如果需要从结构化 JSON 数据生成 Word 文档，请参阅我们的在 Python 中将 JSON 转换为 Word 的教程，其中介绍了如何从 JSON 对象和数组直接创建 Word 内容和表格。

5. 方法三：在 JSON 中保留文档结构

方法一和方法二将段落和表格视为独立的、彼此隔离的元素。但实际上，Word 文档具有有意义的层级关系：标题引出章节，段落提供细节，表格在特定上下文中呈现结构化数据。

在 JSON 中保留这种层级关系，产出的结果对于知识库构建、RAG（检索增强生成）流水线和文档理解系统来说要实用得多。你得到的不再是扁平的文本列表，而是一个保留了原文逻辑脉络的结构化表示。

如何在层级化 JSON 结构中保留标题、段落和表格

具体做法是遍历每个节正文中的所有子对象，判断每个对象的类型（段落或表格），并据此构建结构化的 JSON 表示。对于段落，可以通过检查 StyleName 属性来识别标题。

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

input_file = "项目报告.docx"
output_file = "structured_output.json"

HEADING_STYLES = {
    "Heading1": 1,
    "Heading2": 2,
    "Heading3": 3,
    "Heading4": 4,
}

def get_heading_level(style_name):
    return HEADING_STYLES.get(style_name, None)

def extract_table_data(table):
    rows_data = []
    if table.Rows.Count < 1:
        return {"headers": [], "rows": []}

    header_row = table.Rows[0]
    headers = []
    for c in range(header_row.Cells.Count):
        headers.append(header_row.Cells[c].Paragraphs[0].Text.strip())

    for r in range(1, table.Rows.Count):
        row = table.Rows[r]
        row_dict = {}
        for c in range(row.Cells.Count):
            cell_text = row.Cells[c].Paragraphs[0].Text.strip()
            row_dict[headers[c] if c < len(headers) else f"Column_{c}"] = cell_text
        rows_data.append(row_dict)

    return {"headers": headers, "rows": rows_data}

document = Document()
document.LoadFromFile(input_file)

sections_data = []

for i in range(document.Sections.Count):
    section = document.Sections.get_Item(i)
    content_items = []

    for j in range(section.Body.ChildObjects.Count):
        obj = section.Body.ChildObjects.get_Item(j)

        if isinstance(obj, Paragraph):
            text = obj.Text.strip()
            if not text:
                continue

            heading_level = get_heading_level(obj.StyleName)
            if heading_level:
                content_items.append({
                    "type": "heading",
                    "level": heading_level,
                    "text": text
                })
            else:
                content_items.append({
                    "type": "paragraph",
                    "text": text
                })

        elif isinstance(obj, Table):
            table_data = extract_table_data(obj)
            content_items.append({
                "type": "table",
                "row_count": len(table_data["rows"]),
                "data": table_data
            })

    sections_data.append({
        "section_index": i,
        "content": content_items
    })

document.Close()

result = {
    "source": input_file,
    "section_count": len(sections_data),
    "sections": sections_data
}

with open(output_file, "w", encoding="utf-8") as f:
    json.dump(result, f, indent=2, ensure_ascii=False)

输出示例

以下 JSON 片段展示了标题、段落和表格在层级化输出结构中的表示方式：

{
  "source": "项目报告.docx",
  "section_count": 1,
  "sections": [
    {
      "section_index": 0,
      "content": [
        {
          "type": "heading",
          "level": 1,
          "text": "季度销售报告"
        },
        {
          "type": "paragraph",
          "text": "本报告概述了各区域的销售业绩情况。"
        },
        {
          "type": "heading",
          "level": 2,
          "text": "区域明细"
        },
        {
          "type": "table",
          "row_count": 3,
          "data": {
            "headers": ["区域", "产品", "销量", "营收"],
            "rows": [
              {"区域": "华北", "产品": "笔记本电脑", "销量": "120", "营收": "114000"}
            ]
          }
        }
      ]
    }
  ]
}

转换结果

下图展示了标题、段落和表格如何在层级化 JSON 结构中得以保留。

说明

此方法与前两种的根本区别在于：它使用 section.Body.ChildObjects 按文档顺序遍历所有内容元素，而非分别遍历段落和表格。这样可以保留标题、段落和表格的原始顺序与交错关系。

关键设计决策：

• 通过 StyleName 检测标题：Word 中的标题是应用了"Heading1"、"Heading2"等样式的段落。检查样式名可以区分标题与正文，并记录标题级别。注意，具体的标题样式名可能因 Word 模板或语言设置而异（例如带空格的"Heading 1"，或中文环境下的"标题 1"）。为处理这些差异，可以在查找前对样式名进行归一化：

def get_heading_level(style_name):
    normalized = style_name.lower().replace(" ", "")
    heading_map = {"heading1": 1, "heading2": 2, "heading3": 3, "heading4": 4}
    return heading_map.get(normalized, None)

• ChildObjects 遍历：与 section.Paragraphs（仅返回段落）或 section.Tables（仅返回表格）不同，ChildObjects 按原始顺序返回所有元素。这对保留文档的逻辑结构至关重要。
• 结构化 JSON 输出：每个内容项都包含 type 字段（heading、paragraph 或 table），下游系统可以据此对不同内容类型进行相应处理。

此方法特别适用于：

• RAG 和 AI 流水线：标题结构支持按章节切分文档，提升检索精度
• 知识库构建：层级化 JSON 可以直接映射为树状知识图谱
• 文档理解：保留标题与其关联内容的关系，便于对文档各章节进行语义分析

如果需要从 Word 文档中提取特定类型的内容（如标题、段落或表格），请参阅我们的在 Python 中读取 Word 文档的教程，其中更详细地介绍了内容提取技术。

6. Word 转 JSON 的适用场景

Word 转 JSON 适用于任何需要从 Word 文档中大规模提取结构化数据的场景，常见用例包括：

• AI 和 RAG 文档处理：将 Word 文档转换为 JSON 数据块，用于 LLM 应用中的向量化和检索。方法三的层级结构支持按章节切分，比扁平文本分割的检索效果更好。
• 知识库构建：从以 .docx 文件存储的技术文档、政策文件或操作手册中构建结构化知识库。
• 批量数据提取：从数百份 Word 报表、发票或表单中提取数据，将结果加载到数据库或数据仓库中。
• 合同与简历解析：将法律合同、人事文档或简历转换为结构化 JSON，用于自动化分析和比对。
• API 和 Web 应用的数据交换：通过 REST API 以 JSON 形式提供 Word 文档内容，使 Web 和移动应用无需直接处理 .docx 文件即可消费文档数据。

7. 局限性与最佳实践

局限性

• 没有通用的 Word JSON 结构标准：与 CSV 或 XML 不同，目前没有普遍接受的 Word 内容 JSON 表示格式。你需要根据具体用例来设计结构。
• 复杂格式无法捕获：本教程中的方法提取文本内容和基本的结构元数据（标题级别、表格数据），但不包括字体、颜色、图片、页面布局、页眉/页脚或脚注。如果你的应用需要这些元素，需要额外编写提取逻辑。
• 合并单元格需要特殊处理：Word 表格可以包含合并单元格（水平和垂直均支持）。方法二的逐行提取假设的是规则网格，包含合并单元格的文档可能会产生意外结果。
• 大型文档可能需要分块处理：对于数百页或包含数十个表格的文档，建议逐节或逐表处理，以控制内存占用。

最佳实践

• 先设计 JSON 结构，再编写代码：明确你需要什么（仅文本？标题？表格？完整结构？），然后选择合适的提取方法。
• 用样本文档验证输出：Word 文档的结构和格式差异很大，请用实际文档集中的代表性样本测试转换逻辑。
• 显式指定编码：写入 JSON 文件时始终指定 encoding="utf-8"，避免非 ASCII 文本的编码问题。
• 在 json.dump 中使用 ensure_ascii=False：这可以保留输出中的 Unicode 字符，而非将其转义，对于包含非英文文本的文档尤为重要。

8. 常见问题

可以在 Python 中将 DOCX 转换为 JSON 吗？

可以。使用 Spire.Doc for Python 加载任意 .docx 文件，遍历其中的节、段落和表格，然后用 Python 内置的 json 模块将提取的内容序列化为 JSON。本教程演示了三种方法，从简单的文本提取到完整的结构保留。

开发者最好的 Word 转 JSON 工具是什么？

对于需要批量处理、自动化或自定义 JSON 结构的开发者来说，使用 Spire.Doc 的 Python 方案比在线转换器更灵活。在线工具适用于一次性转换，但无法应对大规模处理、自定义输出格式或集成到自动化流水线中的需求。

可以将 Word 表格转换为 JSON 吗？

可以。遍历 Word 文档中的表格并逐行提取单元格文本，即可将表格数据转换为 JSON 对象数组。本教程的方法二演示了基于表头的键映射方式。

Word 有原生的 JSON 导出选项吗？

没有。Microsoft Word 没有提供内置的 JSON 导出格式。Word 文件可以保存为 DOCX、PDF、HTML、RTF 和纯文本，但转换为 JSON 需要通过编程方式读取文档结构并映射为 JSON 结构。

将 Word 转换为 JSON 时可以保留标题和结构吗？

可以。遍历每个节正文中的所有子对象并检查段落样式名，可以识别标题、正文段落和表格，然后构建保留文档逻辑组织的层级化 JSON 结构。本教程的方法三提供了完整实现。

可以在线将 Word 转换为 JSON 吗？

可以，市面上有在线 Word 转 JSON 工具，能处理一次性转换。但在线工具仅支持单文件处理，且无法自定义 JSON 结构。对于批量处理、自动化流水线或自定义输出结构，使用 Spire.Doc 的 Python 方案更实用，扩展性也更好。

9. 总结

本文演示了如何使用 Spire.Doc for Python 在 Python 中将 Word 文档转换为 JSON。我们介绍了三种复杂度递增的方法：将段落文本提取为扁平 JSON 数组、将 Word 表格转换为结构化 JSON 对象，以及在单一 JSON 输出中保留完整的文档层级（包括标题、段落和表格）。

每种方法各有侧重：纯文本提取适用于索引和向量化，表格提取适用于数据迁移和报表解析，完整结构保留适用于知识库构建和 RAG 流水线。选择与你的需求匹配的方法，并根据具体用例扩展 JSON 结构即可。

Spire.Doc for Python 除了 JSON 转换外，还提供全面的 Word 文档处理能力，包括文档创建、格式设置、邮件合并和格式转换。你可以申请 30 天免费许可证来评估所有功能。

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 响应、数据库记录、配置文件和其他结构化数据源，帮助在小型项目和企业系统中实现文档生成的自动化。

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

在许多 Python 项目中，尤其是涉及 API 对接、数据分析或业务报表的场景，开发者经常需要通过代码实现 Excel 转 JSON 或 JSON 转 Excel。这两种格式各有所长：JSON 适用于结构化数据的交换与存储，而 Excel 则广泛用于业务环境中数据的共享、编辑与展示。

本教程提供一份面向开发者的 JSON 与 Excel 互转完整指南，涵盖嵌套数据处理、Excel 格式设置以及常见转换与编码问题的解决方法。我们将使用 Python 内置的 json 模块处理 JSON 数据，并借助 Spire.XLS for Python 读写 .xlsx、.xls 和 .csv 格式的 Excel 文件，无需安装 Microsoft Excel 或其他第三方软件。

主要内容包括：

• 安装 Spire.XLS for Python
• 为什么选择 Spire.XLS 而非通用库？
• 在 Python 中将 JSON 转换为 Excel
• 在 Python 中将 Excel 转换为 JSON
• 实战示例：处理嵌套 JSON 与复杂 Excel 格式
• 常见错误与解决方法
• 常见问题
• 总结

安装 Spire.XLS for Python

本教程使用该库来生成和解析 Excel 文件（.xlsx、.xls、.csv），完成 JSON 与 Excel 的互转。

首先，从 PyPI 安装 Spire.XLS for Python 包：

pip install spire.xls

对于小型项目，也可以选择 Free Spire.XLS for Python：

pip install spire.xls.free

Spire.XLS for Python 支持 Windows、Linux 和 macOS，无需安装 Microsoft Excel 或任何 COM 组件。

为什么选择 Spire.XLS 而非开源库？

许多开源 Python 库能够胜任简单的 Excel 操作，比如基础数据导出或简单格式设置。需求仅限于简单表格输出时，这些工具通常可以快速完成任务。

然而，当项目需要丰富的 Excel 格式、多工作表报表，或不依赖 Microsoft Office 的独立方案时，Spire.XLS for Python 凭借完整的 Excel 功能集脱颖而出。

如果你的开发团队需要生成精美的 Excel 文件，无论是复杂布局、可视化元素还是面向业务的样式，Spire.XLS 都是一个高效的一体化方案。

在 Python 中将 JSON 转换为 Excel

本节介绍如何使用 Python 将结构化 JSON 数据转换为 Excel 文件。当你需要将 API 响应或内部数据导出为 .xlsx 报表，供业务人员或分析师使用时，这一功能非常实用。

第一步：准备 JSON 数据

我们先准备一份员工记录的 JSON 列表：

[
  {"员工编号": "E001", "姓名": "张伟", "部门": "人力资源部"},
  {"员工编号": "E002", "姓名": "李明", "部门": "信息技术部"},
  {"员工编号": "E003", "姓名": "王芳", "部门": "财务部"}
]

这是 API 返回或日志文件中常见的结构。更复杂的嵌套结构请参见实战示例部分。

第二步：使用 Spire.XLS 将 JSON 转换为 Excel

from spire.xls import Workbook, FileFormat
import json

# 从文件加载 JSON 数据
with open("employees.json", "r", encoding="utf-8") as f:
    data = json.load(f)

# 创建新的 Excel 工作簿并获取第一个工作表
workbook = Workbook()
sheet = workbook.Worksheets[0]

# 将表头写入第一行
headers = list(data[0].keys())
for col, header in enumerate(headers):
    sheet.Range[1, col + 1].Text = header

# 从第二行开始写入数据行
for row_idx, row in enumerate(data, start=2):
    for col_idx, key in enumerate(headers):
        sheet.Range[row_idx, col_idx + 1].Text = str(row.get(key, ""))

# 自动调整所有已使用列的列宽
for i in range(1, sheet.Range.ColumnCount + 1):
    sheet.AutoFitColumn(i)

# 保存 Excel 文件并释放资源
workbook.SaveToFile("output/employees.xlsx", FileFormat.Version2016)
workbook.Dispose()

代码说明：

• Workbook() 初始化 Excel 文件，默认包含三个工作表。
• workbook.Worksheets[] 访问指定的工作表。
• sheet.Range(row, col).Text 向指定单元格写入字符串数据（索引从 1 开始）。
• 第一行包含基于 JSON 键名的列标题，每个 JSON 对象写入下方的新行。
• workbook.SaveToFile() 将 Excel 工作簿保存到磁盘。可以通过 FileFormat 枚举指定格式，例如 Version97to2003 保存为 .xls，Version2007 及以上版本保存为 .xlsx，CSV 保存为 .csv。

生成的 Excel 文件（employees.xlsx），包含员工编号、姓名和部门列。

如果需要纯文本输出格式，也可以使用 Spire.XLS for Python 将 Excel 工作表转换为 CSV 文件。

在 Python 中将 Excel 转换为 JSON

本节介绍如何使用 Python 将 Excel 数据转换回结构化 JSON。当你需要将 .xlsx 文件导入 Web 应用、API 或需要 JSON 输入的数据管道时，这是常见的需求。

第一步：加载 Excel 文件

首先，使用 Workbook.LoadFromFile() 加载 Excel 文件，然后通过 workbook.Worksheets[0] 选择工作表，从而获取需要转换为 JSON 格式的数据。

from spire.xls import Workbook

# 加载 Excel 文件
workbook = Workbook()
workbook.LoadFromFile("products.xlsx")
sheet = workbook.Worksheets[0]

第二步：提取 Excel 数据并写入 JSON

import json

# 获取最后一行和最后一列的索引
rows = sheet.LastRow
cols = sheet.LastColumn

# 从第一行提取表头
headers = [sheet.Range[1, i + 1].Text for i in range(cols)]
data = []

# 使用表头将每行映射为字典
for r in range(2, rows + 1):
    row_data = {}
    for c in range(cols):
        value = sheet.Range[r, c + 1].Value
        row_data[headers[c]] = value
    data.append(row_data)

# 写入 JSON 输出
with open("products_out.json", "w", encoding="utf-8") as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

代码说明：

• sheet.LastRow 和 sheet.LastColumn 检测实际使用的单元格范围。
• 第一行用于提取字段名（表头）。
• 每行映射为一个字典，组成 JSON 对象列表。
• sheet.Range[row, col].Value 返回单元格的显示值。如果文本内容、原始数值或真正的日期对象，可使用 .Text、.NumberValue 或 .DateTimeValue。

使用 Python 从 Excel 数据生成的 JSON 文件：

如果还不熟悉在 Python 中读取 Excel 文件，请参阅完整指南：如何使用 Spire.XLS 在 Python 中读取 Excel 文件。

实战示例：处理嵌套 JSON 与 Excel 格式设置

在实际的 Python 应用中，JSON 数据通常包含嵌套的字典或列表，例如联系方式、配置分组或进度记录。同时，Excel 输出需要遵循清晰、可读的布局，以满足业务或报表需求。

本节演示如何使用 Python 和 Spire.XLS 展平嵌套 JSON 数据并格式化生成的 Excel 工作表，包括合并单元格、应用样式和自动调整列宽。这些功能有助于将复杂数据以清晰的表格形式呈现。

我们使用示例文件 projects_nested.json 来演示整个过程。

第一步：展平嵌套 JSON

示例 JSON 文件（projects_nested.json）：

[
  {
    "项目编号": "PRJ001",
    "项目名称": "人工智能研究",
    "负责人": {
      "姓名": "王建国",
      "邮箱": "wangjg@ lab.cn"
    },
    "阶段": [
      {"阶段名称": "设计", "状态": "已完成"},
      {"阶段名称": "开发", "状态": "进行中"}
    ]
  },
  {
    "项目编号": "PRJ002",
    "项目名称": "云平台迁移",
    "负责人": {
      "姓名": "李志强",
      "邮箱": "lizq@ infra.cn"
    },
    "阶段": [
      {"阶段名称": "评估", "状态": "已完成"}
    ]
  }
]

我们将展平所有嵌套结构，包括"负责人"这样的对象，并将"阶段"等列表汇总为字符串字段。每条 JSON 记录变成一行扁平数据，即使是复杂的嵌套数据也能以可读的摘要形式紧凑地呈现在列中。

import json

# 辅助函数：展平嵌套数据，将字典列表汇总为字符串
# 例如：[{"a":1},{"a":2}] → "a: 1; a: 2"
def flatten(data, parent_key='', sep='.'):
    items = {}
    for k, v in data.items():
        new_key = f"{parent_key}{sep}{k}" if parent_key else k
        if isinstance(v, dict):
            items.update(flatten(v, new_key, sep=sep))
        elif isinstance(v, list):
            if all(isinstance(i, dict) for i in v):
                items[new_key] = "; ".join(
                    ", ".join(f"{ik}: {iv}" for ik, iv in i.items()) for i in v
                )
            else:
                items[new_key] = ", ".join(map(str, v))
        else:
            items[new_key] = v
    return items

# 加载并展平 JSON
with open("projects_nested.json", "r", encoding="utf-8") as f:
    raw_data = json.load(f)

flat_data = [flatten(record) for record in raw_data]

# 从展平后的数据中收集所有唯一键作为表头
all_keys = set()
for item in flat_data:
    all_keys.update(item.keys())
headers = list(sorted(all_keys))  # 一致的、排序后的列顺序

此版本的 flatten() 将字典列表转换为简洁的摘要字符串（例如"阶段名称: 设计, 状态: 已完成; 阶段名称: 开发, 状态: 进行中"），使复杂结构在 Excel 输出中更加紧凑易读。

第二步：使用 Spire.XLS 格式化并导出 Excel

接下来，我们将展平后的项目数据导出为 Excel，并使用 Spire.XLS for Python 的格式化功能来改善布局和可读性，包括设置字体、颜色、合并单元格以及自动调整列宽，从而获得专业的报表外观。

from spire.xls import Workbook, Color, FileFormat

# 创建工作簿和工作表
workbook = Workbook()
sheet = workbook.Worksheets[0]
sheet.Name = "项目报表"

# 标题行：合并并设置样式
col_count = len(headers)
sheet.Range[1, 1, 1, col_count].Merge()
sheet.Range[1, 1].Text = "项目报表（展平 JSON 数据）"
title_style = sheet.Range["A1"].Style
title_style.Font.IsBold = True
title_style.Font.Size = 14
title_style.Font.Color = Color.get_White()
title_style.Color = Color.get_DarkBlue()

# 从展平后的键名生成表头行
for col, header in enumerate(headers):
    cell = sheet.Range[2, col + 1]
    cell.BorderAround() # 为单元格或单元格区域添加外边框
    #cell.BorderInside() # 为单元格区域添加内边框
    cell.Text = header
    style = cell.Style
    style.Font.IsBold = True
    style.Color = Color.get_LightGray()

# 数据行
for row_idx, row in enumerate(flat_data, start=3):
    for col_idx, key in enumerate(headers):
        sheet.Range[row_idx, col_idx + 1].Text = str(row.get(key, ""))

# 自动调整列宽和行高
for col in range(len(headers)):
    sheet.AutoFitColumn(col + 1)
for row in range(len(flat_data)):
    sheet.AutoFitRow(row + 1)

# 保存 Excel 文件
workbook.SaveToFile("output/projects_formatted.xlsx", FileFormat.Version2016)
workbook.Dispose()

这样就能从嵌套 JSON 文件生成一份格式整洁、样式美观的 Excel 工作表，适用于报表、汇报展示或仪表盘。

代码说明

• sheet.Range[].Merge()：将一组单元格合并为一个。此处用于报表标题行（A1:F1）。
• .Style.Font / .Style.Color：用于自定义单元格的字体属性（加粗、字号、颜色）和背景填充。
• .BorderAround() / .BorderInside()：为单元格区域添加外边框/内边框。
• AutoFitColumn(n)：自动调整第 n 列的列宽以适应内容。

使用 Python 展平 JSON 数据后生成的 Excel 文件：

JSON 与 Excel 互转中的常见错误与解决方法

JSON 与 Excel 之间的转换有时会遇到格式、编码或数据结构方面的问题。以下是常见问题及其解决方法：

总结

借助 Spire.XLS for Python，JSON 与 Excel 之间的互转变得高效且可靠。你可以轻松将 JSON 数据转换为格式完善的 Excel 文件（包含表头和样式），也能顺畅地将 Excel 工作表转换回结构化 JSON。该库还能帮助你避免编码错误、嵌套数据复杂性以及 Excel 文件格式陷阱等常见问题。

无论是数据导出、报表生成还是 API 响应处理，Spire.XLS 都能提供一致且高效的方式来实现 .json 与 .xlsx 格式的双向转换。

想要无限制使用所有功能？申请免费临时许可证，即可获取 Spire.XLS for Python 的完整访问权限。

常见问题

Q1：如何在 Python 中将 JSON 转换为 Excel？

可以使用 Python 的 json 模块加载结构化 JSON 数据，然后用 Spire.XLS 等库将其导出为 .xlsx 文件。Spire.XLS 支持写入表头、格式化 Excel 单元格，以及通过展平处理嵌套 JSON。具体步骤请参见上文的 JSON 转 Excel 部分。

Q2：如何在 Python 中解析 JSON 数据？

使用 Python 内置的 json 模块解析 JSON 非常简单：用 json.load() 从文件解析 JSON，或用 json.loads() 解析 JSON 字符串。解析后的结果通常是字典列表，可以遍历并导出为 Excel 或其他格式。

Q3：可以使用 Spire.XLS 在 Python 中将 Excel 导出为 JSON 吗？

可以。Spire.XLS for Python 支持读取 Excel 文件并将工作表数据转换为字典列表，然后用 json.dump() 写入 JSON。整个过程包括提取表头、检测已使用的行和列，以及可选地处理格式化内容。详细实现请参见 Excel 转 JSON 部分。

在许多 Web 应用程序中，集成文档处理能力对于提升用户体验至关重要，它能够实现高效的报告生成和数据处理。React 凭借其基于组件的架构，是前端开发的绝佳选择。通过集成 Spire.Doc for JavaScript，您可以在 React 应用程序中轻松创建和管理 Word 文档。

本指南将逐步介绍如何将 Spire.Doc for JavaScript 集成到您的 React 项目中，涵盖环境搭建和使用示例。

• 在 React 中使用 Spire.Doc for JavaScript 的优势
• 设置开发环境
• 在项目中集成 Spire.Doc for JavaScript
• 使用 JavaScript 创建Word 文件
• 获取免费许可证

在 React 中使用 Spire.Doc for JavaScript 的优势

React 是一个用于构建用户界面的流行 JavaScript 库，已成为现代 Web 开发的基石。而 Spire.Doc for JavaScript 则是一个功能强大的库，旨在简化 Web 应用程序中的文档处理。

通过将 Spire.Doc for JavaScript 集成到 React 项目中，您可以为应用程序添加高级的 Word 文档处理功能。以下是一些主要优势：

• 无缝文档创建：Spire.Doc for JavaScript 支持直接在 React 中创建和编辑文档，无需外部工具即可简化文档管理。
• 跨平台兼容性：Spire.Doc for JavaScript 允许创建兼容多个平台的文档，使用户能够随时随地访问和编辑文档。
• 功能丰富：Spire.Doc for JavaScript 提供丰富的功能，如文本格式化、表格创建和图片插入，非常适合需要文档操作的应用程序。
• 无缝集成：Spire.Doc for JavaScript 兼容多种 JavaScript 框架（包括 React），可以轻松集成到现有项目中，不会干扰您的工作流程。

设置开发环境

步骤 1. 安装 React 和 npm

从官方网站下载并安装 Node.js。请确保选择与您的操作系统相匹配的版本。

安装完成后，您可以在终端中运行以下命令来验证 Node.js 和 npm 是否正常工作：

步骤 2. 创建一个新的 React 项目

在终端中使用 Create React App 创建一个名为 my-app 的新 React 项目：

npx create-react-app my-app

如果您的 React 项目编译成功，应用程序将在 http://localhost:3000 上运行，您可以在浏览器中查看和测试您的应用程序。

要直观地浏览和管理项目中的文件，您可以使用 VS Code 打开该项目。

在项目中集成 Spire.Doc for JavaScript

从我们的网站下载 Spire.Doc for JavaScript，并将其解压到磁盘上的某个位置。下载的产品包集成了 Spire.Doc for JavaScript、Spire.XLS for JavaScript、Spire.PDF for JavaScript 和 Spire.Presentation for JavaScript。要使用 Spire.Doc for JavaScript 的功能，您需要将相应的文件（spire.doc.js、Spire.Doc.Wasm.zip、spire.common.js、Spire.Common.Wasm.zip 以及 _framework 文件夹）复制到项目的 public 文件夹中。

您也可以使用 npm 进行安装。在 VS Code 的终端中运行以下命令：

npm i spire.office

安装完成后，产品包文件将保存在项目的 node_modules/spire.office 路径中。将上面提到的 5 个文件复制到 React 项目的 "public" 文件夹中。

为了确保文本正确渲染，您可以通过自定义路径添加相关的字体文件。在以下示例中，字体被添加到路径：public\。

使用 JavaScript 创建Word 文件

修改 "App.js" 文件中的代码，使用 WebAssembly（WASM）模块生成 Word 文件。具体来说，利用 Spire.Doc for JavaScript 库进行 Word 文件操作。

以下是完整代码：

import React, { useState, useEffect } from 'react';

function App() {
  const [wasmModule, setWasmModule] = useState(null);
  // 加载 Spire.Doc
  useEffect(() => {
    (async () => {
      try {
        const publicUrl = process.env.PUBLIC_URL || '';
        const spireModule = await import(/* webpackIgnore: true */ `${publicUrl}/spire.doc.js`);
        const rawModule = spireModule.default || spireModule;
        window.wasmModule = typeof rawModule === 'function'
          ? await rawModule({ locateFile: p => p.endsWith('.wasm') ? `${publicUrl}/${p}` : p })
          : rawModule;
        setWasmModule(window.wasmModule);
      } catch (error) {
        console.error('加载 spire.doc.js WASM 模块失败:', error);
      }
    })();
  }, []);

  // 生成 Word 文件的函数
  const createWord = async () => {
    const wasmModule = window.wasmModule.spiredoc;
    if (wasmModule) {

      // 将 arial.ttf 字体文件加载到虚拟文件系统（VFS）中
      await window.spire.FetchFileToVFS('arial.ttf', '/Library/Fonts/', `${process.env.PUBLIC_URL}/`);

      // 指定输出文件名
      const outputFileName = 'HelloWorld.docx';

      // 创建一个新文档
      const doc = new wasmModule.Document();

      // 添加一个节
      let section = doc.AddSection();

      // 添加一个段落
      let paragraph = section.AddParagraph();

      // 向段落中添加文本
      paragraph.AppendText('Hello, World!');

      // 将文档保存为 Word 文件
      doc.SaveToFile({ fileName: outputFileName, fileFormat: wasmModule.FileFormat.Docx2013 });

      // 读取保存的文件并将其转换为 Blob 对象
      const modifiedFileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
      const modifiedFile = new Blob([modifiedFileArray], { type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' });

      // 为 Blob 创建 URL 并启动下载
      const url = URL.createObjectURL(modifiedFile);
      const a = document.createElement('a');
      a.href = url;
      a.download = outputFileName;
      document.body.appendChild(a);
      a.click();
      document.body.removeChild(a);
      URL.revokeObjectURL(url);

      // 清理资源
      doc.Dispose();
    }
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>在 React 中使用 JavaScript 创建 Word 文件</h1>
      <button onClick={createWord} disabled={!wasmModule}>
        生成
      </button>
    </div>
  );
}

export default App;

通过在 VS Code 的终端中输入以下命令来启动开发服务器：

npm start

React 应用程序编译成功后，它将在您的默认浏览器中打开，通常地址为 http://localhost:3000。点击"生成"按钮即可创建 "HelloWorld.docx" 文件。

点击"生成"按钮执行'HelloWorld.docx'文档创建生成。

获取免费许可证

如果您希望删除结果文档中的评估消息，或者摆脱功能限制，请该Email地址已收到反垃圾邮件插件保护。要显示它您需要在浏览器中启用JavaScript。获取有效期 30 天的临时许可证。

将 Word 文档转换为 PDF 能够跨平台保持排版一致，同时便于分发和归档。Spire.Doc for JavaScript 基于 WebAssembly 在浏览器端直接完成此转换，通过虚拟文件系统（VFS）管理输入输出文件，无需后端服务支持。

本文介绍两个核心功能点：

• 转换 Word 到 PDF
• 转换 Word 到 PDF 并配置转换选项

有关安装和项目配置，请参考 React 项目中集成 Spire.Doc for JavaScript。以下示例默认已安装 Spire.Doc 并完成 WebAssembly 模块初始化。

转换 Word 到 PDF

Word 转 PDF 仅需几行核心代码。无论是文档加载、格式重排还是文件输出，均通过极简 API 一键触发，让文档处理像复制粘贴一样轻松。

function App() {
  const convertToPDF = async () => {
    // 获取 Spire.Doc WASM 模块
    const docModule = window.wasmModule?.spiredoc;

    // 检查模块是否就绪
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // 将字体和 Word 文件载入 VFS
    await window.spire.FetchFileToVFS('MSYH.TTC', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'AI对人类的影响.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/data/`);

    // 加载文档
    const doc = new docModule.Document();
    doc.LoadFromFile(inputFileName);

    // 保存为 PDF
    const outputFileName = 'ToPDF-result.pdf';
    doc.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.PDF });

    // 从 VFS 读取转换后的文件，触发下载
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/pdf' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);

    // 释放资源
    doc.Dispose();
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To PDF</h1>
      <button onClick={convertToPDF}>
        Generate
      </button>
    </div>
  );
}

export default App;

Word 文档通过 SaveToFile 转换后生成的 PDF 输出

转换 Word 到 PDF 并配置转换选项

在实际业务场景中，仅做基础转换往往不够。Spire.Doc 提供 ToPdfParameterList 类，允许开发者在转换时精细化控制字体嵌入、PDF/A 合规、超链接行为、图片质量和文档加密等参数。以下示例演示如何通过 ToPdfParameterList 保留 Word 标题为 PDF 书签：

function App() {
  const convertWithOptions = async () => {
    // 获取 Spire.Doc WASM 模块
    const docModule = window.wasmModule?.spiredoc;

    // 检查模块是否就绪
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // 将字体和 Word 文件载入 VFS
    await window.spire.FetchFileToVFS('MSYH.TTC', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'AI对人类的影响.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/data/`);

    // 加载文档
    const doc = new docModule.Document();
    doc.LoadFromFile(inputFileName);

    // 创建转换参数对象
    let parames = new docModule.ToPdfParameterList();
    // 不转换手动插入的书签
    parames.CreateWordBookmarks = false;
    // 根据 Heading 1/2/3 自动生成 PDF 书签
    parames.CreateWordBookmarksUsingHeadings = true;  

    // 保存为 PDF（传入配置参数）
    const outputFileName = 'WordToPDF-Options-result.pdf';
    doc.SaveToFile({ fileName: outputFileName, paramList: parames });

    // 从 VFS 读取转换后的文件，触发下载
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/pdf' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);

    // 释放资源
    doc.Dispose();
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To PDF With Options</h1>
      <button onClick={convertWithOptions}>
        Generate
      </button>
    </div>
  );
}

export default App;

通过 ToPdfParameterList 配置转换选项后生成的 PDF 输出

ToPdfParameterList 提供的核心配置选项接口如下：

各选项对应的核心代码片段如下：

// 嵌入所有字体
parames.IsEmbeddedAllFonts = true;

// 嵌入未安装字体（通过 PrivateFontPath 指定字体文件）
let fonts = [new docModule.PrivateFontPath("PT Serif Caption", "PT_Serif-Caption-Web-Regular.ttf")];
parames.PrivateFontPaths = fonts;

// 指定嵌入字体名称列表
parames.EmbeddedFontNameList = ["PT Serif Caption"];

// PDF/A 合规
parames.PdfConformanceLevel = docModule.PdfConformanceLevel.Pdf_A1B;

// 禁用超链接
parames.DisableLink = true;

// 设置图片质量（0-100）
doc.JPEGQuality = 40;

// 保留隐藏文本
parames.IsHidden = true;

// 创建 PDF 书签
parames.CreateWordBookmarks = true;
parames.CreateWordBookmarksUsingHeadings = true;

// PDF 加密
parames.PdfSecurity.Encrypt("password", "E-iceblue", docModule.PdfPermissionsFlags.Default, docModule.PdfEncryptionKeySize.Key128Bit);

将这些选项与基础转换代码组合即可灵活控制 PDF 输出效果。

注意：JPEGQuality 是 Document 对象的属性，不属于 ToPdfParameterList，需直接在 doc 实例上设置。上表中的其他选项均通过 ToPdfParameterList 配置。

常见问题

PDF 中文显示为乱码或空白

原因：WASM 虚拟文件系统中缺少渲染所需的字体文件。SaveToFile 渲染文本时需从 VFS 中读取字体，若未预加载中文字体则文字区域会留白或显示为乱码。

解决：转换前通过 FetchFileToVFS 将支持中文的字体文件（如 MSYH.TTC 或 SIMSUN.TTF）载入 VFS：

await window.spire.FetchFileToVFS(
  'MSYH.TTC', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`
);

SaveToFile 的两种参数传递方式如何选择

原因：SaveToFile 支持 fileFormat 和 paramList 两种参数方式，混淆使用会导致参数不生效。

解决：基础转换使用 fileFormat 直接指定输出格式；使用 ToPdfParameterList 配置选项时将参数对象传给 paramList，两者独立使用：

// 基础转换 — 使用 fileFormat
doc.SaveToFile({ fileName: "output.pdf", fileFormat: docModule.FileFormat.PDF });

// 带选项的转换 — 使用 paramList
let parames = new docModule.ToPdfParameterList();
parames.IsEmbeddedAllFonts = true;
doc.SaveToFile({ fileName: "output.pdf", paramList: parames });

获取免费许可证

如果您希望删除结果文档中的评估消息，或者摆脱功能限制，请该Email地址已收到反垃圾邮件插件保护。要显示它您需要在浏览器中启用JavaScript。获取有效期 30 天的临时许可证。

在 Excel 文档处理场景中，工作表的增删改操作是最基础也最常用的功能之一。Spire.XLS for JavaScript 基于 WebAssembly 在浏览器端直接完成这些操作，通过虚拟文件系统（VFS）管理输入输出文件，无需后端服务支持。

本文介绍三个核心功能点：

• 添加工作表
• 删除工作表
• 移动与重排序工作表

有关安装和项目配置，请参考 React 项目中集成 Spire.XLS for JavaScript。以下示例默认已安装 Spire.XLS 并完成 WebAssembly 模块初始化。

添加工作表

在工作簿中添加新的工作表是日常开发中的高频需求。Spire.XLS for JavaScript 提供了 Add 方法添加工作表并为其命名。添加后可以向新工作表的单元格写入数据，然后保存工作簿。

function App() {
  const startProcessing = async () => {
    // 获取 Spire.XLS WASM 模块
    const xlsModule = window.wasmModule?.spirexls;
    if (!xlsModule) {
      alert('Spire.Xls is not ready yet');
      return;
    }

    // 将字体和 Excel 文件载入 VFS
    await window.spire.FetchFileToVFS('simsun.ttc', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'AddWorksheet.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/data/`);

    // 创建工作簿实例并加载文件
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });

    // 添加新的工作表并命名为 "新增表"
    const sheet = workbook.Worksheets.Add("新增表");
    sheet.Range.get("C5").Text = "这是一张插入的表格.";

    // 自适应列宽
    sheet.AllocatedRange.AutoFitColumns();

    // 保存工作簿
    const outputFileName = "AddWorksheet_output.xlsx";
    workbook.SaveToFile({ fileName: outputFileName });

    // 释放资源
    workbook.Dispose();

    // 从 VFS 读取输出文件，封装为 Blob 并触发下载
    const modifiedFileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([modifiedFileArray], { type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Add Worksheet</h1>
      <button onClick={startProcessing}>
        Start
      </button>
    </div>
  );
}

export default App;

通过 Add 方法在原工作表后添加新工作表。

删除工作表

当需要清理工作簿中的无用工作表时，可以按工作表的名称直接删除。Spire.XLS for JavaScript 的 Remove 方法精准定位并移除目标工作表。

function App() {
  const startProcessing = async () => {
    // 获取 Spire.XLS WASM 模块
    const xlsModule = window.wasmModule?.spirexls;
    if (!xlsModule) {
      alert('Spire.Xls is not ready yet');
      return;
    }

    // 将字体和 Excel 文件载入 VFS
    await window.spire.FetchFileToVFS('simsun.ttc', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'RemoveWorksheet.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/data/`);

    // 创建工作簿实例并加载文件
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });

    // 按工作表名称删除指定的工作表
    const sheet = workbook.Worksheets.get("Sheet2");
    workbook.Worksheets.Remove(sheet);
    // 通过索引删除
    //workbook.Worksheets.RemoveAt(1);

    // 保存工作簿
    const outputFileName = "RemoveWorksheet_output.xlsx";
    workbook.SaveToFile({ fileName: outputFileName });

    // 释放资源
    workbook.Dispose();

    // 从 VFS 读取输出文件，封装为 Blob 并触发下载
    const modifiedFileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([modifiedFileArray], { type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Remove Worksheet</h1>
      <button onClick={startProcessing}>
        Start
      </button>
    </div>
  );
}

export default App;

使用 Remove 方法删除指定名称的工作表。

移动与重排序工作表

调整工作表的顺序是 Excel 文档组织中的常见需求。通过 Spire.XLS for JavaScript 的 MoveWorksheet 方法，可以将工作表移动到目标索引位置，从而实现工作表的重排序。

function App() {
  const startProcessing = async () => {
    // 获取 Spire.XLS WASM 模块
    const xlsModule = window.wasmModule?.spirexls;
    if (!xlsModule) {
      alert('Spire.Xls is not ready yet');
      return;
    }

    // 将字体和 Excel 文件载入 VFS
    await window.spire.FetchFileToVFS('simsun.ttc', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'Sample.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/data/`);

    // 创建工作簿实例并加载文件
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });

    // 获取第一个工作表并将其移动到索引 1
    const sheet = workbook.Worksheets.get(0);
    sheet.MoveWorksheet(1);

    // 保存工作簿
    const outputFileName = "MoveWorksheet_output.xlsx";
    workbook.SaveToFile({ fileName: outputFileName });

    // 释放资源
    workbook.Dispose();

    // 从 VFS 读取输出文件，封装为 Blob 并触发下载
    const modifiedFileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([modifiedFileArray], { type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Move Worksheet</h1>
      <button onClick={startProcessing}>
        Start
      </button>
    </div>
  );
}

export default App;

通过 MoveWorksheet 方法移动第一个工作表到第二个sheet位置。

常见问题

操作工作表时索引超出范围

原因：索引参数超出了工作簿当前工作表的集合范围。

解决：插入前确认工作表的数量，确保索引值在 0 到 worksheets.Count-1 之间。通过 workbook.Worksheets.Count 获取当前工作表总数：

const count = workbook.Worksheets.Count;

按名称删除工作表时提示未找到

原因：指定的工作表名称与工作簿中的实际名称不完全匹配。

解决：删除前先遍历工作表名称进行确认：

for (let i = 0; i < workbook.Worksheets.Count; i++) {
  let name = workbook.Worksheets.get(i).Name;
  console.log(name);
}

获取免费许可证

如果您希望删除结果文档中的评估消息，或者摆脱功能限制，请该Email地址已收到反垃圾邮件插件保护。要显示它您需要在浏览器中启用JavaScript。获取有效期 30 天的临时许可证。