excel-validate-helper

Excel 读取、校验、错误标注和导出工具库，基于 exceljs。

目录

• 安装
• 包中方法介绍
• 使用示例
• 单独使用某方法示例
• 全部方法联合使用示例

安装

你可以通过 npm 或 yarn 直接安装本库：

npm install excel-validate-helper
# 或
yarn add excel-validate-helper

包中方法介绍

• 本包导出了四个核心类：

1. ExcelReader

• 作用：读取 Excel 文件，提取表头和数据。
• 核心方法：
• static async read(file: File, dataStartRow?: number): Promise<{ headers: string[], data: any[][] }>
• 参数：
  • file：浏览器端 File 对象，Excel 文件。
  • dataStartRow：可选，数据起始行（默认为4），表头一般在该行的上一行。
  • 返回：表头字符串数组和数据二维数组。

2. ExcelValidator

• 作用：对读取的 Excel 数据进行校验，包括必填项和联合唯一性校验。
• 核心方法：
• static validate(data: any[][], options: ExcelValidationOptions): { err: CellError[], succ: any[] }
• 参数：
  • data：二维数组，Excel数据。
  • options：配置项，包括必填列索引、唯一列索引、列标题、字段名等。
  • 返回：包含错误信息数组和校验通过的数据数组。

3. ExcelMarker

• 作用：将校验错误标注回 Excel 文件，支持自定义单元格样式和备注。
• 核心方法：
• static async markErrors(file: File, errors: CellError[], options?: MarkerOptions): Promise
• 参数：
  • file：原始 Excel 文件。
  • errors：校验错误数组。
  • options：可选，单元格样式和备注默认值。
  • 返回：包含标注后的错误单元格的 Excel Blob 文件。

4. ExcelExporter

• 作用：将 Blob 文件导出为用户下载。
• 核心方法：
• static export(blob: Blob, fileName?: string): void
• 参数：
  • blob：要导出的文件 Blob。
  • fileName：导出的文件名，默认 export.xlsx。

使用示例

import {
  ExcelReader,
  ExcelValidator,
  ExcelMarker,
  ExcelExporter
} from 'excel-validate-helper';

async function processExcel(file: File) {
  // 1. 读取文件
  const { headers, data } = await ExcelReader.read(file, 4);
  console.log('表头:', headers);
  console.log('数据:', data);

  // 2. 校验数据
  const result = ExcelValidator.validate(data, {
    requiredCols: [0, 1],        // 第一、二列必填
    uniqueCols: [0, 1],          // 第一、二列联合唯一
    colHeaders: headers,
    fieldNames: ['code', 'lineNo', 'pointNo', 'remark'],
    startRowIndex: 4
  });

  if (result.err.length) {
    console.warn('校验失败:', result.err);

    // 3. 标注错误
    const markedBlob = await ExcelMarker.markErrors(file, result.err, {
      defaultNote: '请检查该单元格数据'
    });

    // 4. 导出带标注的Excel
    ExcelExporter.export(markedBlob, '错误标注.xlsx');
  } else {
    console.log('校验通过，数据:', result.succ);
    // 继续业务逻辑处理 result.succ
  }
}

单独使用某方法示例

单独使用 ExcelReader

import { ExcelReader } from 'excel-validate-helper';

const file = ... // 选择的 Excel 文件
const { headers, data } = await ExcelReader.read(file, 4);
console.log(headers, data);

单独使用 ExcelValidator

import { ExcelValidator } from 'excel-validate-helper';

const data = [
  ['A001', 'L01', 'P001', '备注1'],
  ['', 'L02', 'P002', '备注2'], // 第一列为空，必填校验会失败
];

const result = ExcelValidator.validate(data, {
  requiredCols: [0], // 第一列必填
  uniqueCols: [0, 1], // 第一列+第二列联合唯一
  colHeaders: ['编码', '线路号', '点号', '备注'],
  fieldNames: ['code', 'lineNo', 'pointNo', 'remark'],
  startRowIndex: 2
});

console.log('错误信息:', result.err);
console.log('正确数据:', result.succ);

单独使用 ExcelMarker

import { ExcelMarker } from 'excel-validate-helper';

const file = ... // 原始Excel File对象
const errors = [
  { row: 5, col: 0, reason: '编码不能为空' },
  { row: 6, col: 1, reason: '线路号重复' },
];

const markedBlob = await ExcelMarker.markErrors(file, errors, {
  defaultNote: '请修正错误',
  style: {
    font: { color: { argb: 'FF0000FF' }, bold: true },
    fill: { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFFFFF00' } }
  }
});

// 你可以用 ExcelExporter 导出这个 Blob，或上传服务器

单独使用 ExcelExporter

import { ExcelExporter } from 'excel-validate-helper';

const blob = new Blob([/* some excel file data */], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
ExcelExporter.export(blob, '下载文件名.xlsx');

全部方法联合使用示例

同上面的完整示例，整合读取、校验、标注、导出四步，适合常见 Excel 校验场景。

备注

本库依赖 exceljs，浏览器环境中支持现代浏览器。

支持自定义单元格错误样式，方便标注业务需求。

对校验配置灵活，支持必填、联合唯一、多字段映射。

可根据业务需求扩展验证规则和导出功能。