# ExcelUtil

**Repository Path**: yg_cy/ExcelUtil

## Basic Information

- **Project Name**: ExcelUtil
- **Description**: Excel导入工具
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2019-01-19
- **Last Updated**: 2025-04-01

## Categories & Tags

**Categories**: excel-utils

**Tags**: None

## README

# ExcelUtil

#### 介绍
Excel读取组件，V1.0版本

本组件支持读取xlsx与xls两种格式的文件，读取方式可分为两大类一种为规则的，一种为不规则的。
##### 规则的数据
| name | age | birthday |
| -- | -- | -- |
| 张三 | 1 | 2019-01-01 |
| 李四 | 2 | 2018-01-01 |
| 王小二 | 2 | 2018-01-01 |

##### 不规则的数据
| 姓名   | 张三 | 性别 | 男         |
| ------ | ---- | ---- | ---------- |
| 年龄   | 1    | 生日 | 2019-01-01 |

组件通过xml配置文件将表格数据和实体类进行映射，同时提供自定义实现接口和注解两种数据校验方式。


#### 组件UML图
![输入图片说明](https://images.gitee.com/uploads/images/2019/0120/004702_c7a3434d_463972.jpeg "excelUtil.cld.jpg")


#### 采用技术

1. 采用POI3.16进行对excel的读取
2. 使用xml文件对excel数据信息和相关Bean进行配置
3. 采用反射技术对读取的数据进行封装
4. 使用Hibernate Validator 进行对简单数据类型的注解校验

#### 使用说明

##### 1.引入xml配置文件
一个是公共配置文件Base.xml,主要是配置公共的一些信息；一个对excel文件的xml配置文件，这个文件会引用Base.xml的信息

###### Base.xml
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- 导入公共部分 -->
<!-- SheetType -->
<!-- 配置规则的类型的读取类，该类实现了IReadSheet接口，因此也可自行实现不同的读取方式，然后进行配置即可 -->
<sheetType id="Regular" classPath="com.dcits.excelutil.input.readexcel.readsheet.impl.ReadRegularSheet"/>
<!-- 配置不规则的类型的读取类，该类实现了IReadSheet接口，因此也可自行实现不同的读取方式，然后进行配置即可  -->
<sheetType id="Unregular" classPath="com.dcits.excelutil.input.readexcel.readsheet.impl.ReadUnregularSheet"/>

<!-- 配置一些公共的校验类，这些类实现了IValidator接口 -->
<!-- 校验是否是日期 -->
<validatorType id="Date" classPath="com.dcits.excelutil.input.validator.impl.DateValidator"/>
<!-- 校验是否是数值 -->
<validatorType id="Num" classPath="com.dcits.excelutil.input.validator.impl.NumberValidator"/>

```
###### 对excel文件的xml配置


```
<?xml version="1.0" encoding="UTF-8"?>
<!-- 引入公共部分XML文档 -->
<!DOCTYPE doc [
	<!ENTITY Import SYSTEM "Base.xml">
]>
<root>
	<!-- 引入文档：Base.xml -->
    &Import;
    
    <!-- Excel文档读取模式：
    		1、streamMode	：流式读取，适合数据量大的Excel导入，内存占用量小。封装等级较低。目前只适用于规则类型读取，
                                  因此不规则类型只能使用 userMode。
    		2、userMode	：用户模式读取，适合数据量较小的Excel导入，内存占用量大。封装等级高。
     -->
    <readMode mode="userMode"/>
    
    <!-- 规则类型数据的读取 -->
    <bean name="demo" classPath="TestDemo.Demo" sheetName="Sheet1" sheetType="Regular" begin="1" end="">
	<Item field="name" row="" cell="0"  validatorType="" exceptionMessage="" optionData="{}"/>
	<Item field="age" row="" cell="1"  validatorType="Num" exceptionMessage="这不是数字类型" optionData="{isNoNull:true}"/>
	<Item field="birthday" row="" cell="2"  validatorType="Date" exceptionMessage="" optionData="{}"/>
    </bean>
	
    <!-- 不规则类型数据的读取 -->
    <bean name="demo1" classPath="TestDemo.Demo" sheetName="Sheet2" sheetType="Unregular" begin="" end="">
	<Item field="name" row="5" cell="1"  validatorType="" exceptionMessage="" optionData="{}"/>
	<Item field="age" row="7" cell="2"  validatorType="Num" exceptionMessage="" optionData="{isNoNull:true}"/>
	<Item field="birthday" row="5" cell="4"  validatorType="Date" exceptionMessage="" optionData="{}"/>
    </bean>
</root>
```
###### excel文件的xml配置说明
1. \<readMode mode="userMode"/> 中mode可选 streamMode 或 userMode
   一个xml文件只能选择一种模式，当选择streamMode时，只能配置对规则数据的读取。选择userMode时，可同时配置两种类型数据的读取。
2. 一个xml文件中可包含多个bean,一个bean对应一个实体类，一个bean包含多个Item,Item配置实体类属性与单元格信息。
  
  **bean 信息** 

-  **name** ：bean的名称本配置文件唯一， 可根据 name从返回的Map<String, Set<?>>中获取数据，例如：Set<Demo> set = (Set<Demo>) result.get("demo");
-  **classPath** ：实体类路径
-  **sheetName** ：Excel文件的sheet的名称，指明读取哪一个页面
-  **sheetType** ：指明需要读取的数据的类型（规则或不规则），并使用对应的方法读取，此处填写Base.xml中sheetType的id
-  **begin** : 只对规则类型读取有效，指明第几行开始读取
-  **end** : 只对规则类型读取有效，指明读到第几行结束，若为空时，默认读取到最后一行，程序自行判读

 **Item**  
对于规则的数据类型，每一个Item实际上是配置Excel文件那一列数据对应实体类的哪一个属性，程序将一行数据封装到一个对象中
对于不规则的数据类型，每一个Item实际上是配置Excel文件一个单元格的数据对应实体类的哪一个属性，程序将分散的数据封装到一个对象中
-  **field** ： 指明实体类的属性名，采用反射技术根据属性名构建get和set方法，将数据进行封装
-  **row** : 对于规则的数据类型不需要配置，对于不规则的数据类型是指明单元格在哪一行
-  **cell** ： 对于规则的数据类型，配置Excel文件哪一列数据对应实体类的哪一个属性。对于不规则的数据类型，row和cell是一个坐标指明单元格对应实体类的哪一个属性
-  **validatorType** ： 此处填写Base.xml中validatorType 的id。对于需要负责校验的数据类型，可自行实现校验器进行校验，对应常规的数据类型校验建议使用Hibernate Validator 在实体类中进行注解校验。
-  **exceptionMessage** ：仅对validatorType不为空时生效， 校验不通过时，对用户的提示语，可为空。
-  **optionData** ： 校验器中的一个参数，JSON类型格式，为空时填写'{}'。对于Num,Date两个校验器{isNoNull:true}代表该单元格不能为空。


      
##### 2.创建实体类
实体类用于封装数据，可在实体类中使用注解对配置数据校验规则，具体可查看学习Hibernate Validator注解。由于Excel属于第三方工具，用户输入行为不可控制，因此校验是非常重要的事情，否则后患无穷，从实践操作来看，将实体类属性设为String类型最好校验的，其他类型会增加校验工作的复杂性。

``` java
public class Demo {
	
	@Length(min=1,max=20,message="该字段为必填项,长度为不能超过20")
	public String name;
	
	public String age;
	
	public String birthday;
        
        //get,set方法此处省略，使用时不能省略
}
```



##### 将组件导入项目中，调用readExcelClient.read(excelFile, configPath)方法进行读取

```Java
import com.dcits.excelutil.input.ReadExcelClient;

//读取excel文件信息
ReadExcelClient readExcelClient = new ReadExcelClient();
try {
    Map<String, Set<?>> result = readExcelClient.read(new File(filePath), configPath);
    //demo 为bean的名称
    Set<Demo> set = (Set<Demo>) result.get("demo");
    for(Demo d : set){
	System.out.println("姓名:"+d.getName()+"  年龄:"+d.getAge()+"  生日:"+d.getBirthday());
    }
    //demo1 为bean的名称
    Set<Demo> set1 = (Set<Demo>) result.get("demo1");
    for(Demo d : set1){
        System.out.println("姓名:"+d.getName()+"  年龄:"+d.getAge()+"  生日:"+d.getBirthday());
    }
} catch (Exception e) {
    e.printStackTrace();
}

```