Excel转JSON 使用教程
适用插件：Excel转JSON
本教程按插件 v2.0.1 的实际功能编写。
一、这个插件能做什么
Excel转JSON用于把一个或多个 Excel 工作簿批量转换成 JSON 文件。它适合以下场景：
将 Excel 表格数据交给程序、网站或接口使用。
一次转换一个文件夹中的多个工作簿。
同时处理包含多个工作表的工作簿。
按原来的子文件夹结构批量输出 JSON 文件。
插件当前实际支持的 Excel 文件格式为：
.xlsx
.xlsm
插件当前不支持 .xls、.xlsb、.csv 等格式。如果文件是这些格式，请先用 Microsoft Excel 打开，再“另存为” .xlsx 文件。
转换只读取单元格数据，不会把以下 Excel 内容原样放进 JSON：
字体、颜色、边框、行高、列宽等格式。
图片、图表、形状和按钮。
批注、打印设置和页面布局。
宏代码。虽然可以读取 .xlsm 工作簿中的表格数据，但不会执行或保留宏。
二、开始前需要准备什么
建议先准备两个不同的文件夹：
Excel文件夹：存放准备转换的 .xlsx 或 .xlsm 文件。
JSON文件夹：存放转换完成后的 .json 文件。
例如：
D:\待转换Excel D:\转换后的JSON 开始前请检查：
源 Excel 文件可以正常打开。
如果工作簿设置了打开密码，请先取消密码并另存一份；加密工作簿通常无法直接读取。
第一行已经放好字段名称，例如“姓名”“手机号”“订单金额”。
同一个工作表第一行的字段名称尽量不要重复。重复字段名会互相覆盖，后面的同名列可能替代前面的同名列。
建议关闭正在编辑的源 Excel 文件，避免文件被占用。
JSON输出文件夹有足够的磁盘空间和写入权限。
如果输出文件夹中已有同名 JSON，请先备份。插件会覆盖已有的同名输出文件。
三、如何进入插件
打开吉米工具箱。
进入工具箱的“本地应用”列表。
找到“Excel转JSON”。
单击插件卡片或插件名称，进入操作页面。
页面右上角有以下按钮：
返回：回到本地应用列表。
置顶：让插件窗口保持在其他窗口前面；再次单击可取消置顶。
版本标签：显示当前插件版本。
四、认识操作页面
1. Excel文件夹
这里填写或选择源 Excel 所在的文件夹。选择新文件夹后，插件会自动读取其中受支持的 Excel 文件。
2. JSON文件夹
这里填写或选择转换结果的保存文件夹。
3. 加载文件
重新扫描当前 Excel 文件夹，并重建下方文件列表。以下情况建议单击一次“加载文件”：
刚把新 Excel 文件复制进源文件夹。
删除或移动了源文件。
修改了“包含子文件夹”开关。
想清除上一次的状态并重新开始。
4. 开始转换
按照文件列表从前到后开始批量转换。只有文件列表不为空，并且当前没有任务运行时，按钮才可用。
5. 暂停 / 继续
任务运行时显示“暂停”。单击后，队列会在安全处理点暂停，不再开始后续文件。暂停不是强制立即中断，当前文件可能继续处理到安全位置。
暂停后按钮变为“继续”。单击“继续”后，剩余文件继续转换。
6. 包含子文件夹
关闭：只扫描所选 Excel 文件夹最外层的文件。
开启：同时扫描它下面所有层级的子文件夹。
切换开关会重新加载文件列表。
7. 文件列表
文件列表显示文件名、处理进度和处理状态。
单击文件名：复制该文件名或相对路径。
在某一行上单击鼠标右键，再选择“移除”：只把该文件移出本次任务，不会删除磁盘上的源文件。
单击“清空”：清空本次任务列表，不会删除源文件。
任务运行期间不能清空或移除文件。
列表底部可选择每页显示 10、20、50 或 100 条记录。
列表上方的“总文件数”“等待中”“成功”“已跳过”“失败”标签可以单击，用来筛选对应状态。当前转换流程通常使用“等待中”“处理中”“已完成”“失败”和“已取消”；一般不会主动产生“已跳过”结果。
五、最稳妥的使用方法：选择文件夹
这是最适合电脑操作经验较少用户的方法。
在“Excel文件夹”这一行单击“选择”。
在弹出的窗口中找到源文件夹。
单击该文件夹，再确认选择。
查看下方文件列表，确认需要转换的文件已经出现。
如果文件放在子文件夹中，开启“包含子文件夹”。
开关改变后，再确认文件列表数量是否正确。
在“JSON文件夹”这一行单击“选择”。
选择结果保存文件夹。
再次核对源文件夹和输出文件夹，不要选反。
单击“开始转换”。
等待所有目标文件显示“已完成”。
打开 JSON 输出文件夹，检查生成的文件。
六、使用拖拽添加文件
插件支持两种拖拽位置。
1. 拖到文件夹输入框
把源文件夹拖到“Excel文件夹”输入区域，会把它设为源文件夹并加载文件。
把目标文件夹拖到“JSON文件夹”输入区域，会把它设为输出文件夹。
如果误把一个文件拖到文件夹输入框，插件会尝试取这个文件所在的文件夹。
拖拽时请按住文件或文件夹，用鼠标移动到目标区域，看到区域高亮后再松开鼠标。
2. 拖到下方文件列表
可以把 .xlsx、.xlsm 文件或包含这些文件的文件夹直接拖入“文件列表”。
重复文件会自动去重。
“包含子文件夹”关闭时，拖入文件夹只读取该文件夹最外层。
“包含子文件夹”开启时，拖入文件夹会继续读取其子文件夹。
如果尚未选择 Excel 文件夹，插件会根据拖入文件的公共父文件夹自动设置。
已选择 Excel 文件夹后，也可以继续加入其他位置的文件。
多个拖入文件如果来自不同盘符，且插件无法确定公共父文件夹，可能会提示无法加入。
为了让输出目录结构清楚，并避免同名文件互相覆盖，建议把待转换文件整理到同一个总文件夹后再加载。
七、配置项说明与建议
插件会保存常用的文件夹、递归开关和列表分页设置。下次打开时仍应核对路径，避免沿用上次任务的输出位置。
八、Excel数据会怎样变成JSON
1. 具体示例：第一行作为字段名
每个工作表的第一行会作为 JSON 对象的字段名。
例如 Excel 内容：
会得到：
[ { "姓名": "张三", "年龄": 28, "城市": "上海" }, { "姓名": "李四", "年龄": 35, "城市": "杭州" } ]
2. 空白字段名
如果第一行某个单元格为空，插件会自动使用 Column1、Column2、Column3 等名称。数字代表该列在工作表中的位置。
为方便客户理解和后续程序使用，最好在转换前给每一列填写明确且不重复的字段名。
3. 空白行和空白单元格
从第二行开始，整行都是空白的行不会写入 JSON。
某一行中单独为空的单元格会写成空字符串。
只有表头、没有数据行的工作表会得到空数组。
4. 单个工作表
工作簿只有一个工作表时，JSON文件最外层直接是数据数组。
5. 多个工作表
工作簿有多个工作表时，JSON文件最外层是一个对象，工作表名称作为键，每个工作表的数据数组作为值。
例如工作簿有“客户”和“订单”两个工作表：
{ "客户": [ { "客户编号": "C001", "姓名": "张三" } ], "订单": [ { "订单编号": "O001", "金额": 199 } ] }
6. 日期、公式和特殊单元格
日期会转换成 ISO 格式的日期时间字符串，例如 2026-08-09T00:00:00.000Z。
公式单元格优先使用工作簿中已经保存的公式计算结果。插件不会像 Excel 一样重新计算公式。
富文本和超链接主要保留显示文字。
合并单元格通常只有左上角单元格有值，其他位置可能为空，不适合作为规范数据表。
如果公式结果不正确或为空，请先在 Excel 中打开文件，确认公式已经计算完成，保存后再转换。
九、输出文件在哪里
输出规则如下：
book.xlsx 会生成 book.json。
report.xlsm 会生成 report.json。
使用“包含子文件夹”加载的相对路径会在输出文件夹中保留原子文件夹结构。
从已选 Excel 文件夹之外单独加入的文件，通常按文件名直接输出到 JSON 文件夹根目录。
如果输出位置已有同名 .json 文件，新结果会覆盖旧文件。
源 Excel 文件不会因为正常转换而被删除、移动或改名。
例如：
Excel文件夹：D:\待转换Excel 源文件：D:\待转换Excel\华东\客户.xlsx JSON文件夹：D:\转换后的JSON 输出文件：D:\转换后的JSON\华东\客户.json 判断转换成功不能只看输出文件是否存在，应同时确认：
文件列表状态为“已完成”。
进度为 100%。
JSON 文件可以用文本编辑器正常打开。
JSON 中的记录数、工作表名称和关键字段与 Excel 一致。
十、暂停、继续、取消和离开页面
暂停
单击“暂停”后，插件会停止继续取后面的文件。当前正在处理的文件可能继续到安全处理点，因此按钮按下后不要立即关闭电脑。
继续
暂停后单击“继续”，队列从剩余位置继续处理，不需要重新加载文件。
取消
当前页面没有单独的“取消”按钮。任务运行或暂停时，如果单击右上角“返回”，工具箱会提示任务尚未结束。
选择不离开：返回插件，任务继续保持原状态。
确认离开：工具箱会取消整个队列，未完成文件会标记为已取消。
已经完成的 JSON 通常会保留；正在写入或尚未开始的结果不能视为有效结果。重新进入插件后，请重新加载并再次转换未完成文件。
关闭插件、刷新工具箱或退出工具箱时，也不要假定后台任务会继续。需要保留任务时，请先等待全部完成。
十一、常见问题与解决办法
1. 选择文件夹后显示“已加载 0 个文件”
依次检查：
文件扩展名是否为 .xlsx 或 .xlsm。
文件是否放在子文件夹中；如果是，请开启“包含子文件夹”。
路径是否仍然存在。
当前 Windows 账号是否有读取权限。
文件是否只是快捷方式，而不是真实工作簿。
2. “开始转换”按钮是灰色
常见原因：
文件列表为空。
已有任务正在运行。
先选择源文件夹并单击“加载文件”，确认列表中出现文件。
3. 某个文件显示“失败”
把鼠标移到失败状态或进度位置查看提示，然后检查：
文件是否损坏。
文件是否被密码加密。
文件是否实际上不是 .xlsx/.xlsm，只是被手动改了扩展名。
文件是否正在被其他程序独占。
输出文件夹是否有写入权限。
4. JSON中的字段少了或数据被覆盖
检查 Excel 第一行是否有重复字段名。JSON 对象不能同时可靠保留两个完全相同的字段名，建议先把表头改成唯一名称，例如“联系电话1”“联系电话2”。
5. 公式结果为空或不是最新值
插件读取工作簿中已保存的公式结果，不负责重新计算。请用 Excel 打开工作簿，完成计算并保存，再重新转换。
6. 日期看起来与Excel显示不同
Excel中的日期显示格式不会保留，结果会变成标准日期时间字符串。请按实际业务时区检查日期，尤其注意带时间的单元格。
7. 原有JSON被替换
插件会覆盖同名输出文件。需要保留旧结果时，请先复制备份，或选择一个新的空输出文件夹。
8. 两个不同文件输出成了同一个名字
这通常发生在从不同文件夹单独加入同名文件时。把文件整理到同一个总文件夹并保留不同子目录，或者先修改文件名，再重新转换。
9. 暂停后当前文件仍在变化
暂停按队列的安全处理点生效，不是强制截断当前读写操作。请等待当前操作到达安全位置；需要继续时再单击“继续”。
十二、数据安全与使用注意
插件的转换逻辑在本机读取 Excel 并把 JSON 写入本机文件夹，不会由该转换功能上传工作簿内容。
正常转换不会修改源 Excel，但会覆盖输出目录中的同名 JSON。
JSON 是可直接阅读的纯文本文件。源 Excel 中如果有姓名、手机号、身份证号、地址、订单等敏感信息，转换后的 JSON 同样包含这些信息。
不要把敏感 JSON 随意放到公共共享目录、公共网盘或不受控的聊天群。
批量处理前建议备份源文件和已有输出结果。
不要在任务运行时拔出移动硬盘、断开网络磁盘或强制关机。
对重要数据，至少抽查文件总数、每个工作表记录数和几个关键字段。
十三、完成前检查清单
转换前：
源文件都是 .xlsx 或 .xlsm。
工作表第一行是字段名，且字段名不重复。
源文件可以正常打开，没有未解除的密码。
已确认是否需要“包含子文件夹”。
Excel文件夹和JSON文件夹没有选反。
已备份输出文件夹中的同名 JSON。
转换后：
所有目标文件都显示“已完成”和 100%。
成功数量与准备转换的文件数量一致。
输出文件夹中存在对应的 .json 文件。
子文件夹结构符合预期。
已抽查单工作表和多工作表的 JSON 结构。
已核对记录数、字段名、日期和公式结果。
敏感 JSON 已保存到安全位置。
评论区