# excel-handler-support

**Repository Path**: wxl0209/excel-handler-support

## Basic Information

- **Project Name**: excel-handler-support
- **Description**: excel文件导入导出工具，同时提供数据单元格数据验证，会将错误的数据进行标记并添加注释
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2017-08-30
- **Last Updated**: 2021-03-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# excel 工具库

### 项目源于
项目使于 2017.08 月，历时一个月，工作之余开发，为了解决商家后台产品导入导出的问题，已上线。当时没有好用的 excel 工具库，只能自己开发，代码设计上存在缺陷，不具备良好的扩展性和定制化能力，不支持多个 sheet 页的导入导出，这也源于当时设计上的不足。

### 主要功能 

1. 将 excel 文件导入，并转化为自定义 Bean 模型
2. 将自定义 Bean 的集合列表导出为 excel
3. 对导入的excel文件实现检查，错误标记，错误回写功能
4. 支持的导入导出基本类型有，short,char,int,long.float,double,bolean 及对应的包装类。支持String,BigDecimal,Date 类型

### 导入示例


1、excel文件如下

![输入图片说明](https://git.oschina.net/uploads/images/2017/0830/142445_442d72cf_870853.png "1111.png")

2、模型定义 （JavaBean自定义）

![输入图片说明](https://git.oschina.net/uploads/images/2017/0830/142808_3b1cde5e_870853.png "1111.png")

    
    支持的数据类型：
    short,char,int,long.float,double,bolean及对应的包装类。
    支持String,BigDecimal,Date类型。数据类型只是对Bean而言，excel的格式不作限制。


    提供以下注解：
    a）@IngoreNode()：忽略字段注解，字段加上该注解，此字段将被忽略。

    b）@DecimalNode(decimal=4)：小数注解，只针对float,double,BigDecimal有效。
    默认保留2位小数，其它位数可加上此注解指定保留小数位数。

    c)@DateNode(pattern="yyyy-MM-dd"): 日期注解，只针对Date有效。
    默认日期类型会按 yyyy-MM-dd HH-mm-ss格式进行解析和转换，其它类型可定义该注解。

    d）@FieldNode(columnName="输出列名",index=3)：对任意支持的类型有效。
    columnName定义的输出列名，默认与变量名一致;
    index定义该变量对应excel中哪一列，下一个变量会参考上一个变量的index进行累加

    e）@ExcelNode(namespace="test")：编译期注解，需要工程build后才能生效。
    namespace指代不同的导入导出模型，默认不写视为default模型。

    **以上注解对导入导出均有效** 

3、导入代码

![输入图片说明](https://git.oschina.net/uploads/images/2017/0927/180914_be365f9f_870853.png "TimLine图片20170927180855.png")

4、导入结果

![输入图片说明](https://git.oschina.net/uploads/images/2017/0830/145140_a6a9d5ae_870853.png "1111.png")

### 导出示例

1、模型定义，同导入模型

2、导出代码

![输入图片说明](https://git.oschina.net/uploads/images/2017/0927/181131_0f6efc85_870853.png "TimLine图片20170927181124.png")

3、导出结果

![输入图片说明](https://git.oschina.net/uploads/images/2017/0830/145416_bb1f20c3_870853.png "1111.png")

    说明：
    Bean中定义password指向了第C列，B列未定义，被跳过。
    C列password指定了输出列名，固导出时有自定义的列名。
    F，G列均为小数，F列未指定任何定义默认保留2位小数，G列指定保留3位小数
    H，I列均为日期类型，前者默认日期格式，后者定义yyyy-MM-dd

### 校验示例

1、校验器定义


![输入图片说明](https://git.oschina.net/uploads/images/2017/0927/181644_d4e71c4c_870853.png "TimLine图片20170927181648.png")


    说明：需要继承 Validator，并实现 validate方法;
    检查器内可调用 terminated()函数来实现中止所有行检查；
    在检查过程中遇到异常，会跳过当前行，继续下一行的检查;
    通过 setMessage() 函数来设置错误消息；


2、代码示例


![输入图片说明](https://git.oschina.net/uploads/images/2017/0927/181840_c24766aa_870853.png "TimLine图片20170927181847.png")


3、检查结果导出


    说明：导出结果有错误的单元格会标红，并加上批注。
    因为判断条件是 age > 12, 则设置错误消息，如果检查器调用了 terminated() 函数，
    会中止后续行的检查。

![输入图片说明](https://git.oschina.net/uploads/images/2017/0927/174814_9b83c67c_870853.png "TimLine图片20170927174658.png")


### API

1、ExcelHandler


![输入图片说明](https://git.oschina.net/uploads/images/2017/0830/151934_1e5ad7bd_870853.png "1111.png")

    ImportEntry importExcel(File newfile)
    // 按defualt模型导入 newfile
    ImportEntry importExcel(InputStream instream)
    // 按defualt模型导入 instream
    ImportEntry importExcel(String namespace, File newfile)
    // 按 namespace 模型导入 newfile
    ImportEntry importExcel(String namespace, InputStream instream)
    // 按 namespace 模型导入 instream

2、ImportEntry


![输入图片说明](https://git.oschina.net/uploads/images/2017/0927/174011_41b2c5ee_870853.png "TimLine图片20170927173854.png")

    void skipHeader(int row);
    // 跳过前几行，一般跳过表头，默认跳过第一行。
    boolean hasError();
    // 调用 validate() 后，判断导入数据是否有错误
    void validate();
    // 当定义了检查器时，调用该方法进行数据检查
    void setValidator(Validator validator);
    // 手动设置检查器
    List<Object> getModelObject() throws InstanceException ;
    // 将导入的excel转换为default模型的集合列表
    <T> List<T> getModelObject(Class<T> modelClass) throws InstanceException;
    // 将导入的excel转换为 modelClass 模型的集合列表
    void writeExcel(File newfile) throws IOException;
    // 将包含错误信息的excel或格式转换后的数据回写到newfile中
    void writeExcel(OutputStream output) throws IOException;
    // 将包含错误信息的excel或格式转换后的数据回写到output中
    List<ErrorField> getErrorFeilds();
    // 返回所有校验错误的对象及其错误信息


3、ExportEntry

![输入图片说明](https://git.oschina.net/uploads/images/2017/0830/152154_6c33f43e_870853.png "1111.png")


    <T> void exportEntitys(List<T> entitys , File newexcel)
    // 按 default 模型将entitys 导出到 newexcel 中
    <T> void exportEntitys(Class<T> basicClass ,List<T> entitys ,File newfile)
    // 按 basicClass 模型将entitys 导出到 newexcel 中
    <T> void exportEntitys(List<T> entitys , OutputStream output)
    // 按 default 模型将entitys 导出到 output 中
    void exportEntitys(Class basicClass , List entitys , OutputStream output)
    // 按 basicClass 模型将entitys 导出到 output 中
    importEntry.illegalReflectValue();
    // 将查询数据填充入excel文件


### 附加说明
    
    对于调用过 validate() 函数的excel，writeExcel 会导出该excel，并标记错误数据的
    单元格，从而可以直观的修改单元格并重新提交上传，进行再次验证，修改成功的单元格会被
    标记为浅绿色，错误的内容依然会被红色标记。

### 2018-3月新增
    通常我们有需求上传一个excel模板，比如一列的用户id，期望服务器查询出用户数据并在excel单元格内进行填充，并作返回excel文件这时该工具也同样凑效。新增函数 illegalReflectValue()