fast-excel-js
v0.1.4
Published
一个基于exceljs的简单易用的excel解析库
Readme
Fast Excel JS
一个基于 ExcelJS 的简单易用的 Excel 解析库，支持多种数据读取模式和强大的数据验证功能。
特性
- 🚀 简单易用 - 通过配置化的方式定义数据结构，无需复杂的代码逻辑
- 📊 多种读取模式 - 支持表单模式、表格模式和原始模式三种数据读取方式
- ✅ 数据验证 - 内置丰富的数据验证功能，包括类型检查、范围验证、正则匹配等
- 🔧 灵活配置 - 支持自定义格式化函数、验证函数和依赖项检查
- 🎯 精确定位 - 支持行列精确定位，可处理复杂的 Excel 布局
- 🌐 TypeScript 支持 - 完整的 TypeScript 类型定义
安装
npm install fast-excel-js
# 或
pnpm add fast-excel-js
# 或
yarn add fast-excel-js快速开始
import { readExcelData } from 'fast-excel-js';
import fs from 'fs';
// 读取 Excel 文件
const buffer = fs.readFileSync('example.xlsx');
// 定义数据结构
const sheetDefinition = {
sheetName: '数据表',
dataAreaDef: {
mode: 'table',
scope: [2, 10, 1, 5], // [起始行, 结束行, 起始列, 结束列]
headers: {
name: { type: 'string', col: 1 },
age: { type: 'number', col: 2 },
email: { type: 'string', col: 3 },
birthday: { type: 'date', col: 4 },
isActive: { type: 'boolean', col: 5 }
}
}
};
// 解析数据
const data = await readExcelData(buffer, sheetDefinition);
console.log(data);数据读取模式
1. 表单模式 (Form Mode)
适用于读取固定位置的单个数据项，如表单字段。
const formDefinition = {
sheetName: '表单',
dataAreaDef: {
mode: 'form',
properties: {
title: { type: 'string', row: 1, col: 2 },
author: { type: 'string', row: 2, col: 2 },
createDate: { type: 'date', row: 3, col: 2 },
// 嵌套表格
items: {
mode: 'table',
scope: [5, 10, 1, 3],
headers: {
itemName: { type: 'string', col: 1 },
quantity: { type: 'number', col: 2 },
price: { type: 'number', col: 3 }
}
}
}
}
};2. 表格模式 (Table Mode)
适用于读取表格数据，支持横向和纵向表格。
// 横向表格（默认）
const tableDefinition = {
sheetName: '数据表',
dataAreaDef: {
mode: 'table',
scope: [2, 100, 1, 5],
headers: {
name: { type: 'string', col: 1 },
age: { type: 'number', col: 2, min: 0, max: 120 },
email: { type: 'string', col: 3, regexp: '^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$' },
salary: { type: 'number', col: 4, formatter: (val) => val * 1000 },
status: { type: 'string', col: 5, required: true }
},
seqProperty: 'index', // 自动添加序号列
breakWhenEmpty: true // 遇到空行时停止读取
}
};
// 纵向表格
const verticalTableDefinition = {
sheetName: '纵向数据',
dataAreaDef: {
mode: 'table',
vertical: true,
scope: [1, 5, 2, 100],
headers: {
name: { type: 'string', row: 1 },
value: { type: 'number', row: 2 }
}
}
};3. 原始模式 (Raw Mode)
直接读取指定区域的原始数据，返回二维数组。
const rawDefinition = {
sheetName: '原始数据',
dataAreaDef: {
mode: 'raw',
scope: [1, 10, 1, 5],
breakWhenEmpty: {
row: [5, 8], // 在第5行或第8行遇到空值时停止
col: [3] // 在第3列遇到空值时停止
}
}
};数据验证
基础验证
const validationDefinition = {
name: {
type: 'string',
col: 1,
required: true, // 必填
minLength: 2, // 最小长度
maxLength: 50, // 最大长度
regexp: '^[a-zA-Z\\s]+$' // 正则验证
},
age: {
type: 'number',
col: 2,
min: 0, // 最小值
max: 120, // 最大值
validateError: 'skip' // 验证失败时跳过该行
}
};自定义验证
const customValidationDefinition = {
email: {
type: 'string',
col: 3,
validate: (value) => {
if (!value.includes('@')) {
return '邮箱格式不正确';
}
return undefined; // 验证通过
}
},
confirmPassword: {
type: 'string',
col: 5,
dependencyValidate: (value, item) => {
if (value !== item.password) {
return '确认密码与密码不匹配';
}
return undefined;
}
}
};验证错误处理
undefined(默认): 忽略验证错误'throw': 抛出异常，停止解析'skip': 跳过当前行/列，继续解析
数据格式化
const formatterDefinition = {
price: {
type: 'number',
col: 4,
formatter: (value) => {
// 将分转换为元
return value / 100;
}
},
fullName: {
type: 'string',
col: 5,
formatter: (value) => {
// 转换为大写
return value?.toString().toUpperCase();
}
}
};嵌套表格
支持在表格中嵌套子表格，适用于复杂的数据结构。
const nestedTableDefinition = {
sheetName: '订单数据',
dataAreaDef: {
mode: 'table',
scope: [2, 50, 1, 10],
headers: {
orderNo: { type: 'string', col: 1 },
customerName: { type: 'string', col: 2 },
// 嵌套表格：订单项目
items: {
mode: 'table',
inline: true, // 内联模式
repeat: 3, // 重复3次
headers: {
productName: { type: 'string', col: 3 },
quantity: { type: 'number', col: 4 },
price: { type: 'number', col: 5 }
}
}
}
}
};多工作表处理
const multiSheetDefinitions = [
{
sheetName: '用户数据',
dataAreaDef: {
mode: 'table',
scope: [2, 100, 1, 5],
headers: {
name: { type: 'string', col: 1 },
email: { type: 'string', col: 2 }
}
}
},
{
sheetName: '订单数据',
dataAreaDef: {
mode: 'table',
scope: [2, 200, 1, 4],
headers: {
orderNo: { type: 'string', col: 1 },
amount: { type: 'number', col: 2 }
}
}
}
];
const data = await readExcelData(buffer, multiSheetDefinitions);
// 返回: { '用户数据': [...], '订单数据': [...] }列引用方式
支持多种列引用方式：
const columnDefinition = {
name: { type: 'string', col: 1 }, // 数字
email: { type: 'string', col: 'B' }, // 字母
phone: { type: 'string', col: 'AC' }, // 多字母
address: { type: 'string', col: '5' } // 字符串数字
};错误处理
try {
const data = await readExcelData(buffer, sheetDefinition);
console.log(data);
} catch (error) {
if (error.message.includes('Validation failed')) {
console.error('数据验证失败:', error.message);
} else {
console.error('解析错误:', error.message);
}
}API 参考
readExcelData(buffer, sheetDataDef)
参数:
buffer: ArrayBuffer- Excel 文件的二进制数据sheetDataDef: SheetDataDefinition | SheetDataDefinition[]- 工作表数据定义
返回:
Promise<Record<string, unknown>>- 解析后的数据对象
类型定义
interface DataPropertyDef {
type: 'string' | 'number' | 'boolean' | 'datetime' | 'date';
row?: string | number;
col?: string | number;
required?: boolean;
formatter?: (val: CellValueType) => CellValueType;
max?: number;
min?: number;
maxLength?: number;
minLength?: number;
regexp?: string;
validate?: (val: CellValueType) => string | undefined;
validateError?: 'throw' | 'skip';
dependencyValidate?: (val: CellValueType, item: FormDataType | ItemDataType) => string | undefined;
}
interface SheetDataDefinition {
sheetName: string;
dataAreaDef: {
[prop: string]: DataAreaDef | DataPropertyDef;
} | DataAreaDef;
}许可证
MIT License
贡献
欢迎提交 Issue 和 Pull Request！
更新日志
v0.0.9
- 初始版本发布
- 支持表单、表格、原始三种读取模式
- 完整的数据验证功能
- TypeScript 支持