EXCEL

导入

通过如下方式导入excel api

import excel from "svr-api/excel";

方法

/**
 * 读取和生成Excel文件的相关API
 */
import { File } from "./fs";

/**
 * 读取excel文件数据到json格式。
 * 
 * @returns `SheetJSONData` 数组
 */
export function readExcelToJSON(args: {
	/**excel文件路径、或文件流 */
	excelFile: string | File | InputStream;
	/**读取哪个sheet，可传递序号（0开始）或sheet名，不传递时读取所有sheet */
	sheet?: string | number;
    /**如何分析列名
     * 1. `auto` 自动分析，系统自动根据excel的数据格式，分析出数据区域和列头区域
     */
	columnName?: "auto" | "firstRow" | "none";
	/**文件拓展名，用于文件名本身不带后缀的情况下补充说明。 */
	fileExtension?: "xls" | "xlsx";
	/**每个sheet的最大行数，sheet数据行超过限制则截取前sheetMaxRow行。 */
	sheetMaxRow?: number;

}): SheetJSONData[];

/**excel一个sheet的数据转换成的json */
export interface SheetJSONData {
	/**sheet名称 */
	sheetName: string;
	/**数据行行数 */
	rowCount: number;
	/**列数 */
	colCount: number;
	/**所有的列名，当无法分析列名是为空 */
	columns: TableFieldMetadata[];
	/**所有的单元格的数据，如果能正确分析列头，那么只包含数据区域的数据 */
	rows: any[][];
}

/**
 * 打开一个excel文件。支持读取excel数据。
 * 
 * @param excelFile excel文件路径、或文件流
 * @returns 返回一个`poi`的[Workbook](https://poi.apache.org/apidocs/dev/org/apache/poi/ss/usermodel/Workbook.html)接口。
 */
export function openExcelFile(args: {excelFile: string | File | InputStream}): Workbook;

/**
 * 创建一个新的excel工作表对象，用于创建新的excel文件。
 */
export function createWorkbook(): Workbook;

/**
 * TODO
 * 保持excel文件 
 */
export function saveExcelFile(workbook: Workbook, excelFile: string | File): void;


/** 提供一些常用的工具方法*/

/**
 * 判断是否为日期，excel的日期以数值类型存储，但可以通过显示格式判断出是否为日期。
 */
export function isDate(cell: Cell): boolean;

/**
 * 判断是否为日期，excel的时间以数值类型存储，但可以通过显示格式判断出是否为时间。
 */
export function isTime(cell: Cell): boolean;

/**
 * excel工作簿，代表一个excel文件。
 * 参考 <https://poi.apache.org/apidocs/dev/org/apache/poi/ss/usermodel/Workbook.html> 把常用的接口定义出来
 */
export interface Workbook {
	/**
	 * 关闭工作簿，并关闭使用的所有流，请务必在使用结束、或发生异常后调用本方法。
	 */
	close: () => void;

	/**
	 * 获取excel的sheet数量。
	 */
	getNumberOfSheets: () => number;

	/**
	 * 获取第index（从0开始）个sheet。
	 * @throws IllegalArgumentException 如果index小于0或者大于最大数量。
	 */
	getSheetAt: (index: number) => Sheet;

	/**
	 * 获取名为name的sheet。
	 */
	getSheet: (name: string) => Sheet;


	/**不常用的函数都通过这个访问，避免出现编译错误 */
	[anything: string]: any;
}

/**
 * excel工作表，一个workbook包含一个或多个sheet。
 */
export interface Sheet {
	/**
	 * 获取逻辑上的数据行（从0开始），若获取的行未定义则返回null。
	 */
	getRow: (rowNum: number) => Row;

	/**
	 * 获取当前sheet名称。
	 */
	getSheetName: () => string;

	/**
	 * 获取首行的序号（从0开始）。
	 */
	getFirstRowNum: () => number;

	/**
	 * 获取最后一行的序号（从0开始）。
	 */
	getLastRowNum: () => number;

	/**
	 * 获取所有合并单元格的范围。
	 * @returns List<org.apache.poi.ss.util.CellRangeAddress>
	 */
	getMergedRegions: () => Array<MergeRegion>;

	/** 更多参见，org.apache.poi.ss.usermodel.Sheet*/
	[anything: string]: any;
}


export interface Row {
	/**
	 * 获取第cellNum列的单元格，若该列未定义，则返回null。
	 */
	getCell: (cellNum: number) => Cell;

	/**
	 * 获取定义的第一个单元格序号。
	 */
	getFirstCellNum: () => number;

	/**
	 * 获取定义的最后一个单元格的序号。
	 */
	getLastCellNum: () => number;

	/** 更多参见，org.apache.poi.ss.usermodel.Row*/
	[anything: string]: any;
}

export interface Cell {

	/**
	 * 获取单元格类型
	 */
	getType: () => CellType;

	/**
	 * 获取double类型的值。
	 * @throws 若单元格不能解析为double，则抛出NumberFormatException异常。
	 */
	getNumericCellValue: () => number;

	/**
	 * 获取string类型的值。
	 */
	getStringCellValue: () => string;

	/**
	 * 获取boolean类型的值。
	 *@throws 若{@link #getCellType()}的返回值不是{@link CellType#BOOLEAN}、{@link CellType#BLANK}或{@link CellType#FORMULA}，则抛出IllegalStateException异常。
	 */
	getBooleanCellValue: () => boolean;

	/** 更多参见，org.apache.poi.ss.usermodel.Cell*/
	[anything: string]: any;
}

/**
 * excel工作表中的合并单元格区域。
 */
export interface MergeRegion {
	getFirstColumn: () => number;
	getLastColumn: () => number;
	getFirstRow: () => number;
	getLastRow: () => number;
	isInRange: (rowInd: number, colInd: number) => boolean;
}


/**
 * 单元格数据存储类型。
 */
 export const enum CellType {
	/** 数值类型 */
	NUMERIC = "NUMERIC",

	/** 字符串类型 */
	STRING = "STRING",

	/** 布尔类型 */
	BOOLEAN = "BOOLEAN",
	
	/** 空值 */
	BLANK = "BLANK",

	/** 计算公式 */
	FORMULA = "FORMULA",

	/** 异常单元格 */
	ERROR = "ERROR"
}