sheet_to_json() 是 SheetJS/xlsx 库中最常用的方法之一，用于将 Excel 工作表（Worksheet）转换为 JSON 格式数据。下面我将全面讲解它的用法、参数配置和实际应用场景。
基本语法
javascript
复制
下载
const jsonData = XLSX.utils.sheet_to_json(worksheet, options);
参数说明：
-
worksheet (必需)：工作表对象，通过
workbook.Sheets[sheetName]获取 -
options (可选)：配置对象，控制转换行为
配置选项详解
1. header - 控制表头处理方式
| 值 | 类型 | 说明 | 示例输出 |
|---|---|---|---|
0 | 数字 | 使用第一行作为键名（默认） | [{A:1, B:"Text"}] |
1 或 'A' | 数字/字符串 | 返回二维数组 | [["A","B"], [1,"Text"]] |
null | null | 不使用表头行，自动生成列名（A,B,C...） | [{A:1, B:"Text"}] |
['列1','列2'] | 数组 | 自定义列名 | [{列1:1, 列2:"Text"}] |
2 | 数字 | 使用第三行作为表头（0基索引） | [{第三行的值:1}] |
'A2:C2' | 字符串 | 指定表头范围 | [{A2的值:1, B2的值:"Text"}] |
2. range - 控制数据范围
javascript
复制
下载
// 只解析A2到D10区域
sheet_to_json(worksheet, { range: "A2:D10" })// 从第5行开始解析（0基索引）
sheet_to_json(worksheet, { range: 4 })
3. raw - 原始值处理
| 值 | 说明 |
|---|---|
true | 返回原始值（数字、布尔值等），日期返回Excel序列值（默认） |
false | 返回格式化后的字符串值（如日期显示为"2023-01-01"） |
4. dateNF - 日期格式
指定日期格式化字符串：
javascript
复制
下载
sheet_to_json(worksheet, { dateNF: "yyyy-mm-dd", // ISO格式// dateNF: "yyyy年mm月dd日", // 中文格式raw: false
})
5. defval - 空单元格默认值
javascript
复制
下载
// 空单元格返回空字符串
sheet_to_json(worksheet, { defval: "" })// 空单元格返回null
sheet_to_json(worksheet, { defval: null })
6. 其他选项
| 选项 | 类型 | 说明 |
|---|---|---|
blankrows | boolean | 是否包含空行（默认false） |
skipHidden | boolean | 是否跳过隐藏行列（默认false） |
orientation | string | 数据方向（'rows'或'columns'） |
返回值类型
根据 header 设置返回不同类型：
javascript
复制
下载
// header: 0 (默认) → 对象数组
[{ 列1: 值1, 列2: 值2 }, ...]// header: 1 → 二维数组
[[标题1, 标题2], [值1, 值2], ...]// header: null → 对象数组（自动列名）
[{ A: 值1, B: 值2 }, ...]
实际应用示例
示例1：基本用法（对象数组）
javascript
复制
下载
const workbook = XLSX.readFile("data.xlsx");
const worksheet = workbook.Sheets[workbook.SheetNames[0]];// 默认转换：第一行为表头
const data = XLSX.utils.sheet_to_json(worksheet);
console.log(data);
// 输出: [{ 姓名: "张三", 年龄: 25 }, ...]
示例2：处理日期
javascript
复制
下载
const data = XLSX.utils.sheet_to_json(worksheet, {raw: false, // 获取格式化值dateNF: "yyyy-mm-dd" // 日期格式
});// 或转换为Date对象
const rawData = XLSX.utils.sheet_to_json(worksheet, { raw: true });
const processed = rawData.map(row => ({...row,入职日期: excelDateToJSDate(row.入职日期)
}));
示例3：复杂表头处理
javascript
复制
下载
// 跳过前两行（标题和说明）
const data = XLSX.utils.sheet_to_json(worksheet, {header: 2, // 第三行作为表头range: 2 // 从第三行开始解析
});// 自定义列名
const customData = XLSX.utils.sheet_to_json(worksheet, {header: ["id", "name", "date"],range: "A3:C100" // 指定范围
});
示例4：二维数组处理
javascript
复制
下载
const matrix = XLSX.utils.sheet_to_json(worksheet, {header: 1 // 二维数组
});// 获取表头
const headers = matrix[0];// 处理数据行
const rows = matrix.slice(1).map(row => {return headers.reduce((obj, header, index) => {obj[header] = row[index];return obj;}, {});
});
性能优化技巧
-
限制数据范围：使用
range只解析需要的数据javascript
复制
下载
sheet_to_json(worksheet, { range: "A1:D1000" }) -
避免格式化：大数据集使用
raw: true提升性能javascript
复制
下载
// 快速读取原始数据 const rawData = sheet_to_json(worksheet, { raw: true }); -
分块处理：大型文件分块读取
javascript
复制
下载
// 分页处理 const page1 = sheet_to_json(worksheet, { range: "A1:D1000" }); const page2 = sheet_to_json(worksheet, { range: "A1001:D2000" }); -
使用Web Workers：避免阻塞UI线程
javascript
复制
下载
// 在Web Worker中处理Excel const worker = new Worker("excel.worker.js"); worker.postMessage(worksheet);
常见问题解决方案
问题1：日期显示为数字
解决方案：
javascript
复制
下载
// 方案1：使用格式化字符串
const data = sheet_to_json(worksheet, { raw: false, dateNF: "yyyy-mm-dd" });// 方案2：手动转换
const rawData = sheet_to_json(worksheet, { raw: true });
const processed = rawData.map(row => ({...row,日期字段: excelDateToJSDate(row.日期字段)
}));
问题2：表头不在第一行
解决方案：
javascript
复制
下载
// 指定表头行（0基索引）
const data = sheet_to_json(worksheet, { header: 2 }); // 第三行作为表头// 或自定义列名
const data = sheet_to_json(worksheet, {header: ["ID", "名称", "日期"]
});
问题3：空单元格处理
解决方案：
javascript
复制
下载
// 设置默认值
const data = sheet_to_json(worksheet, { defval: null });// 或过滤空行
const data = sheet_to_json(worksheet).filter(row => Object.values(row).some(val => val !== null)
);
问题4：特殊字符处理
解决方案：
javascript
复制
下载
// 清理键名中的特殊字符
const cleanData = sheet_to_json(worksheet).map(row => {const cleanRow = {};for (const key in row) {const cleanKey = key.replace(/[\s\.]/g, "_");cleanRow[cleanKey] = row[key];}return cleanRow;
});
Vue3 + TypeScript 最佳实践
typescript
复制
下载
import * as XLSX from 'xlsx';interface Product {id: string;name: string;date: Date;quantity: number;
}const parseExcel = (file: File): Promise<Product[]> => {return new Promise((resolve, reject) => {const reader = new FileReader();reader.onload = (e) => {try {const data = new Uint8Array(e.target?.result as ArrayBuffer);const workbook = XLSX.read(data, { type: 'array' });const sheet = workbook.Sheets[workbook.SheetNames[0]];// 获取原始数据const rawData = XLSX.utils.sheet_to_json(sheet, { raw: true,defval: null}) as Record<string, any>[];// 转换数据const products: Product[] = rawData.map(row => ({id: String(row['产品ID']),name: String(row['产品名称']),date: excelDateToJSDate(Number(row['生产日期'])),quantity: Number(row['数量'])}));resolve(products);} catch (error) {reject(error);}};reader.readAsArrayBuffer(file);});
};// Excel日期转换函数
const excelDateToJSDate = (excelDate: number): Date => {return new Date((excelDate - 25569) * 86400 * 1000);
};
总结
xlsx.utils.sheet_to_json() 是处理 Excel 数据的核心方法，关键点在于：
-
使用
header控制数据结构（对象数组或二维数组） -
使用
raw和dateNF处理特殊类型（如日期） -
使用
range优化性能，限制解析范围 -
结合 TypeScript 类型定义确保数据安全
根据实际需求选择合适的配置组合，可以高效地将 Excel 数据转换为前端可用的 JSON 格式。
