> 技术文档 > xlsx.utils.sheet_to_json() 方法详解

xlsx.utils.sheet_to_json() 方法详解

sheet_to_json() 是 SheetJS/xlsx 库中最常用的方法之一,用于将 Excel 工作表(Worksheet)转换为 JSON 格式数据。下面我将全面讲解它的用法、参数配置和实际应用场景。

基本语法

javascript

复制

下载

const jsonData = XLSX.utils.sheet_to_json(worksheet, options);

参数说明:

  1. worksheet (必需):工作表对象,通过 workbook.Sheets[sheetName] 获取

  2. 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: \"\" })// 空单元格返回nullsheet_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; }, {});});

性能优化技巧

  1. 限制数据范围:使用 range 只解析需要的数据

    javascript

    复制

    下载

    sheet_to_json(worksheet, { range: \"A1:D1000\" })
  2. 避免格式化:大数据集使用 raw: true 提升性能

    javascript

    复制

    下载

    // 快速读取原始数据const rawData = sheet_to_json(worksheet, { raw: true });
  3. 分块处理:大型文件分块读取

    javascript

    复制

    下载

    // 分页处理const page1 = sheet_to_json(worksheet, { range: \"A1:D1000\" });const page2 = sheet_to_json(worksheet, { range: \"A1001:D2000\" });
  4. 使用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 数据的核心方法,关键点在于:

  1. 使用 header 控制数据结构(对象数组或二维数组)

  2. 使用 raw 和 dateNF 处理特殊类型(如日期)

  3. 使用 range 优化性能,限制解析范围

  4. 结合 TypeScript 类型定义确保数据安全

根据实际需求选择合适的配置组合,可以高效地将 Excel 数据转换为前端可用的 JSON 格式。