JSON 工具指南：在文档、数据与 JSON 之间互相转换
本指南将说明 JSON 系列工具如何读写文件，PDF 转 JSON 和 Word 转 JSON 生成的文档格式是怎样的，以及每种任务应选用哪个工具。
为什么选择 JSON
JSON 是程序、网络服务和 AI 模型最容易读取的数据格式：带有命名字段的对象、列表、数字、文本、true、false 和 null，仅此而已。文档和电子表格并不是以这种方式存储的。这一系列工具在两个方向上弥合了这一差距：它们将 PDF、Word 文件、电子表格、CSV、YAML 和 XML 转换为 JSON，也能将 JSON 转换回人们可以阅读的文件，例如 PDF、Word、Excel、CSV 和 HTML。
每个工具都在我们的服务器上通过安全连接运行，并在 60 分钟内删除上传的文件。文本内容可以直接粘贴，无需上传文件。
针对不同任务应选用哪个工具
| 您拥有 | 您想要 | 使用 |
|---|---|---|
| 一个 PDF | 以数据形式获得文字、表格和元数据 | PDF 转 JSON |
| 一个 Word 文档 | 以数据形式获得标题、段落、列表和表格 | Word 转 JSON |
| 一个 Excel 工作簿 | 记录、行或列 | Excel 转 JSON |
| 一个 CSV 或 TSV 文件 | 一个带类型值的 JSON 数组 | CSV 转 JSON |
| 一个 YAML 文件 | 相同数据的 JSON 版本 | YAML 转 JSON |
| 一个 XML 文件 | 对象、属性和数组 | XML 转 JSON |
| JSON | 一份可供阅读或打印的 PDF | JSON 转 PDF |
| JSON | 一个 Excel 工作簿 | JSON 转 Excel |
| JSON | 一个 CSV 文件 | JSON 转 CSV |
| JSON | 一份可编辑的 Word 文档 | JSON 转 Word |
| JSON | 一个网页 | JSON 转 HTML |
| JSON | 用于配置文件的 YAML | JSON 转 YAML |
| JSON | 供其他系统使用的 XML | JSON 转 XML |
| 混乱或无效的 JSON | 干净、有效的 JSON | JSON 格式化工具 |
| 两个 JSON 文件 | 一份变更清单 | 比较 JSON |
Markdown 也有自己的一对工具：Markdown 转 JSON 可导出文档树，JSON 转 Markdown 可将 JSON 转换为 Markdown 大纲或表格。
文档格式
PDF 转 JSON 和 Word 转 JSON 写出的是相同的结构，因此同一套代码可以同时处理这两种文件。顶层始终包含以下字段：
{
"format": "acepdfmd-document",
"version": 1,
"source": {"type": "pdf", "filename": "report.pdf", "title": "Q3 Report", "pages": 12},
"pages": [{"number": 1, "width": 612, "height": 792, "words": 380, "text": "..."}],
"blocks": [
{"type": "heading", "level": 1, "text": "Q3 Report"},
{"type": "paragraph", "text": "Revenue grew..."},
{"type": "list", "ordered": false, "items": [{"level": 0, "text": "Europe"}]},
{"type": "table", "header": ["Region", "Q3"], "rows": [["Europe", 1200.5]]}
],
"tables": [{"index": 1, "page": 3, "rows": [["Region", "Q3"], ["Europe", 1200.5]]}],
"form_fields": [{"name": "email", "type": "text", "value": "[email protected]"}],
"extraction": {"engine": "pdf_to_markdown/layout", "mode": "structure", "ocr": false, "warnings": []}
}
各字段的含义如下：
- source：文件的基本情况及其携带的元数据（标题、作者、主题、关键词、创建和修改日期、页数）。Word 文件还会附加字数、表格数和图片数。
- pages：每个 PDF 页面对应一个条目，包含其以磅为单位的尺寸、旋转角度、字数以及文字内容。Word 文件没有 pages 字段，因为 Word 只在打印时才会进行分页排版。
- blocks：按阅读顺序排列的文档内容。类型包括 heading（层级为 1 到 6）、paragraph（可带有来自 Word 的可选样式名称）、list（有序或无序，条目带有嵌套层级）、table（表头加带类型的行）、code、blockquote、rule 和 image。
- tables：对于 PDF，列出每一个检测到的表格，标明其所在页码，若表格跨页，还会标明结束页码。看起来像数字的单元格会以数字形式呈现。
- form_fields：仅当 PDF 包含表单时才会出现。每个字段都带有名称、类型（text、choice、button 或 signature）和当前值。
- extraction：说明使用了哪种转换方式、您选择的模式、是否需要 OCR，以及任何警告信息，例如某个表格未能被识别。
该格式的第 1 版今后只会新增字段；已有字段的名称和含义不会改变。
表格数据与嵌套结构
CSV 和 Excel 是扁平的，JSON 不是。当 JSON 转换为 CSV 或 Excel 时，嵌套对象会被展平为用点号连接的列名，数组则会展平为带索引的列名，因此一条包含 customer 对象和 items 数组的订单记录，会变成诸如 customer.name、items[0].sku 和 items[1].sku 这样的列。当 CSV 或 Excel 转换回 JSON 时，以这种方式写出的表头会被重新构建为嵌套对象和数组。像版本号或缩写中常见的普通点号，则会被原样保留，不做处理。
值在导入时会被赋予类型：数字变成数字，true 和 false 变成布尔值，空单元格变成 null，其他内容则保留为字符串。从 Excel 导出的日期会写成 ISO 8601 字符串，因为 JSON 没有日期类型。当带前导零的标识符必须原样保留时，请将值类型选项切换为文本。
验证与修复
每个 JSON 工具都以相同的方式验证输入内容。无效文件会被拒绝，并给出第一个错误所在的行号和列号，以及该行的简短摘录。JSON 格式化工具 还可以修复人们最常粘贴的错误：注释、多余的逗号、单引号字符串、未加引号的键、首字母大写的 True、False 和 None、NaN 和 Infinity，以及包裹文本的代码围栏。当应用了某项修复时，结果会告知您，因此不会有任何行为在您不知情的情况下悄然改变。
隐私
上传的文件和粘贴的文本会在我们的服务器上处理，并在 60 分钟内删除；详情请参见隐私指南。超过这段时间后，任何内容都不会被保留，也不会被用于任何其他目的。