xlsx.utils.sheet_to_json() 方法详解
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
[{A:1, B:\"Text\"}]
[\'列1\',\'列2\']
[{列1:1, 列2:\"Text\"}]
2
[{第三行的值: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
false
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: \"\" })// 空单元格返回nullsheet_to_json(worksheet, { defval: null })
6. 其他选项
blankrows
skipHidden
orientation
返回值类型
根据 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中处理Excelconst 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 => { 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[]; // 转换数据 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 格式。