# Excel数据读取器

**Repository Path**: qisx7749/readExcel

## Basic Information

- **Project Name**: Excel数据读取器
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-29
- **Last Updated**: 2025-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Excel数据读取器

一个使用JavaScript读取Excel文件并生成对象的工具库，支持多种数据格式和自定义处理。

## 功能特性

- 📊 读取Excel文件（.xlsx, .xls格式）
- 🔍 支持多工作表读取
- 📝 自动识别列标题
- 🎯 灵活的数据处理选项
- ⚡ 高性能数据处理
- 🛡️ 完善的错误处理

## 安装

1. 克隆或下载项目到本地
2. 安装依赖包：

```bash
npm install
```

## 依赖

- **xlsx**: Excel文件读写库
- **Node.js**: 运行环境

## 使用方法

### 基本用法

```javascript
const { readExcelWithHeaders, readExcelToObjects, getExcelInfo } = require('./index');

// 读取Excel文件（第一行作为列标题）
const data = readExcelWithHeaders('./sample.xlsx');
console.log(data);

// 获取Excel文件信息
const info = getExcelInfo('./sample.xlsx');
console.log(info);
```

### 主要函数

#### 1. `readExcelWithHeaders(filePath, sheetName)`
读取Excel文件，第一行作为列标题，返回对象数组。

**参数：**
- `filePath` (string): Excel文件路径
- `sheetName` (string, 可选): 工作表名称，默认读取第一个工作表

**返回值：** 对象数组，每个对象代表一行数据

**示例：**
```javascript
const data = readExcelWithHeaders('./data.xlsx');
// 返回格式：[{name: '张三', age: 25}, {name: '李四', age: 30}]
```

#### 2. `readExcelToObjects(filePath, sheetName)`
读取Excel文件，支持自定义数据处理，返回处理后的对象数组。

**参数：**
- `filePath` (string): Excel文件路径
- `sheetName` (string, 可选): 工作表名称

**返回值：** 处理后的对象数组

**示例：**
```javascript
const data = readExcelToObjects('./data.xlsx');
// 支持空列标题处理，自动生成列名
```

#### 3. `getExcelInfo(filePath)`
获取Excel文件的详细信息。

**参数：**
- `filePath` (string): Excel文件路径

**返回值：** 包含文件信息的对象

**示例：**
```javascript
const info = getExcelInfo('./data.xlsx');
console.log(info);
// 输出：
// {
//   fileName: 'data.xlsx',
//   filePath: './data.xlsx',
//   sheetCount: 2,
//   sheets: ['Sheet1', 'Sheet2'],
//   fileSize: 12345,
//   sheetDetails: [...]
// }
```

### 高级用法

#### 指定工作表
```javascript
// 读取指定的工作表
const data = readExcelWithHeaders('./data.xlsx', 'Sheet2');
```

#### 数据过滤和处理
```javascript
const data = readExcelToObjects('./data.xlsx');

// 过滤数据
const filteredData = data.filter(row => {
    return row.age && parseInt(row.age) > 18;
});

// 数据转换
const transformedData = data.map(row => ({
    fullName: `${row.firstName} ${row.lastName}`,
    age: parseInt(row.age),
    isAdult: parseInt(row.age) >= 18
}));
```

## 运行示例

项目包含完整的示例代码，可以直接运行：

```bash
# 运行主程序示例
npm start

# 运行详细示例
node example.js

# 开发模式（自动重启）
npm run dev
```

## 支持的Excel格式

- `.xlsx` - Excel 2007+ 格式
- `.xls` - Excel 97-2003 格式
- 支持多工作表
- 支持合并单元格
- 支持公式（读取计算结果）

## 数据格式要求

### 推荐格式
- 第一行作为列标题
- 列标题清晰明确
- 数据连续，无空行
- 数据类型一致

### 示例Excel结构
```
姓名    年龄    城市    职业
张三    25     北京    工程师
李四    30     上海    设计师
王五    28     广州    产品经理
```

## 错误处理

库包含完善的错误处理机制：

```javascript
try {
    const data = readExcelWithHeaders('./data.xlsx');
    console.log(data);
} catch (error) {
    console.error('读取失败:', error.message);
    // 错误类型包括：
    // - 文件不存在
    // - 工作表不存在
    // - 文件格式错误
    // - 权限问题
}
```

## 性能优化建议

1. **大文件处理**: 对于大型Excel文件，考虑分批处理
2. **内存管理**: 处理完成后及时释放变量
3. **缓存策略**: 重复读取同一文件时考虑缓存

## 常见问题

### Q: 支持哪些Excel版本？
A: 支持Excel 97-2003 (.xls) 和 Excel 2007+ (.xlsx) 格式。

### Q: 如何处理空单元格？
A: 空单元格默认值为空字符串，可以通过参数自定义。

### Q: 支持读取公式吗？
A: 支持，会读取公式的计算结果。

### Q: 如何处理中文列名？
A: 完全支持中文列名，无需特殊处理。

## 贡献

欢迎提交Issue和Pull Request来改进这个项目！

## 许可证

MIT License

## 更新日志

### v1.0.0
- 初始版本发布
- 支持基本的Excel读取功能
- 提供多种数据处理选项
- 完善的错误处理机制