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 - 控制表头处理方式

2. range - 控制数据范围

javascript

复制

下载

// 只解析A2到D10区域
sheet_to_json(worksheet, { range: "A2:D10" })

// 从第5行开始解析（0基索引）
sheet_to_json(worksheet, { range: 4 })

3. raw - 原始值处理

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. 其他选项

返回值类型

根据 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中处理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 数据的核心方法，关键点在于：

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

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

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

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

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