# Excel2Json - Excel转JSON工具

## 工具介绍
Excel2Json是一款功能强大的Excel文件转换工具，帮助您快速将Excel表格数据转换为结构化的JSON格式。它通过直观的配置表设计，支持多区域划分、区域间引用嵌套和丰富的数据类型转换，让您无需编程知识即可完成复杂数据结构的定义和转换。

## 核心特性
- ✅ 支持多种数据类型：字符串、数字、布尔值、日期、数组、对象引用
- ✅ 智能区域识别：自动识别和解析Excel中的数据区域
- ✅ 灵活的引用系统：支持区域间嵌套引用和循环引用检测
- ✅ 自动类型转换：根据字段定义自动转换数据类型
- ✅ 错误检测和提示：提供详细的格式验证和错误信息
- ✅ 批量处理：支持多Sheet和多区域的批量转换

## 快速开始（3分钟上手）

基于项目中的测试文件 `tests/工作簿1.xlsx`，最简单的Excel转JSON只需要4行表格：

### 最简单的用户列表

| Root:Array | （空） | （空） | （空） |
|-----------|--------|--------|--------|
| 姓名 | 年龄 | 邮箱 | 状态 |
| name:string | age:number | email:string | status:boolean |
| 张三 | 25 | zhangsan@email.com | true |
| 李四 | 30 | lisi@email.com | false |

**转换结果：**
```json
[
{
"name": "张三",
"age": 25,
"email": "zhangsan@email.com",
"status": true
},
{
"name": "李四",
"age": 30,
"email": "lisi@email.com",
"status": false
}
]
```

**只需要4步：**
1. 第1行：`区域名:类型`（如 `Root:Array`）
2. 第2行：字段说明（可以留空）
3. 第3行：字段定义（如 `name:string`）
4. 第4行开始：实际数据

**上传Excel文件 → 自动转换 → 导出JSON**，就是这么简单！


## 一、Excel表格结构基础

### 1.1 表格结构（4行制）
Excel表格只需要固定的4行格式：

1. **第1行**：区域标题（如：`Root:Array`）
2. **第2行**：字段说明（可以留空）
3. **第3行**：字段定义（如：`name:string`）
4. **第4行开始**：实际数据

### 1.2 区域类型选择

| 区域类型 | 含义 | 适用场景 | JSON结果 |
|---------|------|---------|---------|
| `Array` | 多条数据 → 数组 | 用户列表、商品清单 | `[]` |
| `Object` | 单条数据 → 对象 | 个人信息、系统配置 | `{}` |

**选择规则：**
- **列表数据** → 用 `Array`（如用户列表、订单列表）
- **单条数据** → 用 `Object`（如个人信息、系统设置）


## 二、数据类型（超简单版）

### 2.1 基础类型（最常用）

| 类型 | 说明 | Excel中写 | 转换后 | 示例 |
|-----|------|----------|-------|-----|
| `string` | 文字 | 张三 | "张三" | 姓名、邮箱、ID |
| `number` | 数字 | 25 | 25 | 年龄、价格、数量 |
| `boolean` | 是/否 | true/false | true/false | 状态、开关 |
| `date` | 日期 | 2023-10-15 | "2023-10-15T00:00:00.000Z" | 生日、创建时间 |

### 2.2 数组类型（多个值用分号隔开）

| 类型 | 说明 | Excel中写 | 转换后 | 示例 |
|-----|------|----------|-------|-----|
| `Array` | 文字数组 | 张三;李四;王五 | ["张三", "李四", "王五"] | 标签、技能列表 |
| `Array` | 数字数组 | 1;2;3;4;5 | [1, 2, 3, 4, 5] | 评分、编号列表 |

**小贴士：**
- 数组用 `;` 分隔：`张三;李四;王五`
- 支持混合类型：`1;张三;true` → `[1, "张三", true]`
- 布尔值支持：`true`/`false`、`1`/`0`


## 三、引用类型（连接其他表格）

### 3.1 区域引用基础

| 类型 | 说明 | Excel中写 | 作用 |
|-----|------|----------|-----|
| `区域名` | 引用单个对象 | UserInfo | 自动获取UserInfo区域的第一条数据（Object类型区域）|
| `Array` | 引用数组区域 | Array | 引用区域名，自动获取该Array类型区域的所有数据 |
| `Object` | 引用对象区域 | Object | 引用区域名，自动获取该Object类型区域的数据 |

**示例（基于实际测试文件）：**

**Root区域：**

| Root:Object | （空） | （空） |
|------------|--------|--------|
| 用户列表 | 游戏信息 | |
| users:Array | gameInfo:Object | |
| UserList | Info | |

**UserList区域：**

| UserList:Array | （空） |
|---------------|--------|
| 用户名 | 账号 |
| user_name:string | user_accoutn:number |
| 张三 | 123 |
| 李四 | 345 |

**Info区域：**

| Info:Object | （空） |
|------------|--------|
| 版本号 | 游戏名称 |
| version:number | game_name:string |
| 1 | 小游戏 |

**转换结果：**
```json
{
"users": [
{"user_name": "张三", "user_accoutn": 123},
{"user_name": "李四", "user_accoutn": 345}
],
"gameInfo": {
"version": 1,
"game_name": "小游戏"
}
}
```

**引用规则：**
- 字段类型写 `Array` 或 `Object`，数据单元格填写要引用的区域名
- 引用的区域名必须在同一Sheet中存在
- `Array` 引用会获取对应Array类型区域的所有数据行
- `Object` 引用会获取对应Object类型区域的数据
- 引用过程完全自动，只需在数据单元格填写区域名即可


## 四、完整示例

### 4.1 基于测试文件的完整示例（Sheet1）
基于项目中的 `tests/工作簿1.xlsx` Sheet1：

**完整表格结构：**

**Root区域：**

| Root:Object | （空） | （空） | （空） | （空） | （空） | （空） |
|------------|--------|--------|--------|--------|--------|--------|
| 描述1 | 描述2 | 描述3 | 描述4 | 描述5 | 描述6 | 描述7 |
| col1:number | col2:string | col3:boolean | col4:Array | col5:Array | col6:Array | col7:Object |
| 1 | abc123 | FALSE | 1;2;3;4;5 | a;b;c;d;e | UserList | Info |

**UserList区域：**

| UserList:Array | （空） |
|---------------|--------|
| 用户名 | 账号 |
| user_name:string | user_accoutn:number |
| 张三 | 123 |
| 李四 | 345 |

**Info区域：**

| Info:Object | （空） |
|------------|--------|
| 版本号 | 游戏名称 |
| version:number | game_name:string |
| 1 | 小游戏 |

**转换结果：**
```json
{
"col1": 1,
"col2": "abc123",
"col3": false,
"col4": [1, 2, 3, 4, 5],
"col5": ["a", "b", "c", "d", "e"],
"col6": [
{"user_name": "张三", "user_accoutn": 123},
{"user_name": "李四", "user_accoutn": 345}
],
"col7": {"version": 1, "game_name": "小游戏"}
}
```

**说明：**
- `col1-col3`: 基础类型（数字、字符串、布尔值）
- `col4-col5`: 类型化数组（`Array` 和 `Array`）
- `col6`: 引用类型Array，数据单元格填写"UserList"表示引用UserList区域的所有数据
- `col7`: 引用类型Object，数据单元格填写"Info"表示引用Info区域的数据

### 4.2 基于测试文件的完整示例（Sheet2）
基于项目中的 `tests/工作簿1.xlsx` Sheet2：

**完整表格结构：**

| Root:Array | （空） | （空） |
|-----------|--------|--------|
| 姓名 | 年龄 | 时间 |
| name:string | age:number | time:date |
| 张三 | 18 | 2000-01-01 |
| 李四 | 14 | 2000-01-02 |
| 王五 | 17 | 2000-01-03 |

**转换结果：**
```json
[
{
"name": "张三",
"age": 18,
"time": "2000-01-01T00:00:00.000Z"
},
{
"name": "李四",
"age": 14,
"time": "2000-01-02T00:00:00.000Z"
},
{
"name": "王五",
"age": 17,
"time": "2000-01-03T00:00:00.000Z"
}
]
```


## 五、注意事项和最佳实践

### 5.1 重要提醒
- ✅ **区域标题**：必须在第1行第1列，格式：`区域名:类型`
- ✅ **字段定义**：第3行，格式：`字段名:类型`
- ✅ **区域类型**：只能是 `Array` 或 `Object`
- ✅ **引用语法**：字段类型写 `Array` 或 `Object`，数据单元格填写区域名称

### 5.2 常见问题

| 问题 | 原因 | 解决方法 |
|-----|------|---------|
| 区域未识别 | 标题格式错误 | 检查是否为 `区域名:类型` 格式 |
| 类型错误 | 数据与类型不匹配 | 确认数据格式与字段类型一致 |
| 引用失败 | 区域名拼写错误 | 检查区域名称大小写和拼写 |
| 数据缺失 | 空行或格式问题 | 确认数据行不为空 |

### 5.3 高级技巧
1. **多Sheet支持**：每个Sheet可独立配置，分别转换
2. **循环引用检测**：系统自动检测并防止死循环
3. **性能优化**：支持大文件处理，自动内存管理
4. **错误恢复**：提供详细错误信息和修复建议

**就是这么简单！3分钟配置，永久使用！** 🚀