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;
	/**
	 * 读取哪个sheet
	 *
	 * 支持sheet序号（0开始）或sheet名称
	 *
	 * 默认读取所有sheet
	 */
	sheet?: string | number;
	/**
	 * 如何分析列名
	 * 
	 * 1. `auto` 自动分析，系统自动根据excel的数据格式，分析出数据区域和列头区域
	 * 2. `firstRow` 第一行作为列头
	 */
	columnName?: "auto" | "firstRow";
	/**
	 * 文件拓展名，用于文件名本身不带后缀的情况下补充说明。
	 */
	fileExtension?: FileType.XLS | FileType.XLSX;
	/**
	 * 单个sheet最大数据行数，最大值为`10000`条，超过限制时截取前`10000`条数据
	 */
	sheetMaxRow?: number;

}): SheetJSONData[];

/**
 * 描述Excel文件中的一个sheet
 * 
 * 使用场景：
 * 
 * * 用于读取Excel文件数据
 * * 将数据或查询结果写入到Excel文件
 */
export interface SheetJSONData {
	/**sheet名称 */
	sheetName: string;
	/**数据行行数 */
	rowCount: number;
	/**列数 */
	colCount: number;

	/**
	 * 字段信息
	 * 
	 * * 读取文件时，为分析出的字段信息，可能为空
	 * * 写入文件时，为每列数据对应的字段信息
	 */
	columns?: TableFieldMetaData[];

	/**
	 * 所有的单元格的数据
	 *
	 * * 读取文件时，如果能正确分析列头，那么只包含数据区域的数据
	 * * 写入时只包含数据，列头信息设置在{@link SheetJSONData#columns}中
	 */
	rows: any[][];
}

/**
 * 打开一个excel文件。支持读取excel数据。
 * 
 * @param excelFile 支持文件对象、路径、输入流
 * @param encoding 编码格式，默认为`UTF-8`
 * @returns 返回一个`poi`的[Workbook](https://poi.apache.org/apidocs/dev/org/apache/poi/ss/usermodel/Workbook.html)接口。
 */
export function openExcelFile(excelFile: File | string | InputStream, encoding?: string): Workbook;

/**
 * 创建一个sheet对象用于写入Excel文件
 */
export function createSheetJSONData(sheetName: string): SheetJSONData;


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

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

/**
 * 判断是否为时间，excel的时间以数值类型存储，但可以通过显示格式判断出是否为时间。
 * 
 * @param cell 目标单元格
 */
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"
}


/**
 * 导出excel表格的列样式
 */
interface ExcelCellStyleInfo {
	/**
	 * 列的对其方式
	 */
	align?: "right" | "center" | "left" | "justify";

	/**
	 * 缩进，单元格内部文字前的空格数量。
	 */
	indent?: number;

	/** 
	 * 背景色，只支持纯色填充。
	 * 
	 * 颜色格式
	 * 1. #FFFFFF
	 * 2. rgba(115,203,160,0.15)
	 */
	background?: string;
	
	/**
	 * 字体，字体颜色只支持纯色。
	 * 
	 * 颜色格式：
	 * 1. #FFFFFF
	 * 2. rgba(115,203,160,0.15)
	 */
	font: FontInfo;
}

interface ExcelDataColumnInfo {
	/**
	 * 存在两行列头是，第一行列头标题。如果相邻的多列此标题相同则合并单元格。
	 */
	groupCation?: string;
	/**
	 * 列标题。
	 */
	caption?: string;

	/** 列宽 */
	width?: number;

	/**
	 * 数据类型。如数值、文本。
	 */
	dataType?: FieldDataType;

	/**
	 * 显示格式。
	 *
	 * 只支持excel识别的显示格式。如果是@txt 等需作用字段描述的显示格式，应该在`BulkDataReader`中直
	 * 接返回文本字段数据。
	 */
	displayFormat?: string;

	/**
	 * 标题列样式。
	 */
	headStyle?: ExcelCellStyleInfo;
	/**
	 * 数据列样式。优先级高于外层设置的表体整体的背景色和偶数行背景色。
	 */
	bodyStyle?: ExcelCellStyleInfo;
}

/**
 * 描述excel文件中一个sheet中列表。
 */
interface ExcelSheetWriteArgs {
	/**
	 * sheet名称。
	 */
	sheetName: string;

	/**
	 * 表述列表的一列。
	 */
	columns: Array<ExcelDataColumnInfo>;

	/**
	 * 是否显示列头，默认为true。
	 */
	includeHeader?: boolean;

	/**
	 * 表体所有数据行的背景色，优先作用列上设置的列上设置了背景。
	 * 
	 * 支持"#ffffff"或"rgba(r, g, b, a)"格式的颜色值。
	 */
	dataRowBackground?: string;

	/**
	 * 偶数行被背景色，优先作用列上设置的列上设置了背景。
	 * 
	 * 支持"#ffffff"或"rgba(r, g, b, a)"格式的颜色值。
	 */
	evenRowBackground?: string;

	/**
	 * 标题行行高
	 */
	headerRowHeight?: number;

	/**
	 * 数数据行行高
	 */
	bodyRowHeight?: number;

	/**
	 * 表体数据。
	 */
	data: any[][] | Array<JSONObject> | BulkDataReader | ((sheetName: string) => any[][] | Array<JSONObject> | BulkDataReader);
}

/**
 * 写入列表数据到excel文件
 * 
 * @param file 目标文件，支持文件对象、路径、输出流
 * @param sheets 需要保存的excel数据对象
 * @param encoding 编码格式，默认为`UTF-8`
 */
export function writeExcel(args: {
	/**
	 * 要产生的Excel文件。
	 */
	file: File | string | OutputStream,
	/**
	 * 加载Excel模版。
	 * 
	 * 模版文件可以提供一个样式“外壳”，后续在{@link writeExcel()}时，可以只将数据”填充“入Excel模版即可。
	 * @todo
	 */
	templateFile?: File | string,
	/**
	 * excel中的sheet，如果指定了{@link templateFile}，那么sheet中可以不携带样式信息，只携带数据信息。
	 */
	sheets: Array<ExcelSheetWriteArgs>;
}): void