ExcelUtils (youci-excel 1.0.4 API)

java.lang.Object
- cn.zxinrun.excel.util.ExcelUtils<T>

public class ExcelUtils<T>
extends Object

Excel工具类

Since:: 1.0
Author:: Mr.Zhang

Field Summary

Fields
Modifier and Type	Field and Description
`Class<T>`	`clazz` 实体对象
`static String`	`FORMULA_REGEX_STR`
`static String[]`	`FORMULA_STR`
`static int`	`sheetSize` Excel sheet最大行数，默认65536

Constructor Summary

Constructors
Constructor and Description

ExcelUtils(Class<T> clazz)
构造方法，初始化工具类

Constructors
Constructor and Description
`ExcelUtils(Class<T> clazz)` 构造方法，初始化工具类

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`org.apache.poi.ss.usermodel.Cell`	`addCell(Excel attr, org.apache.poi.ss.usermodel.Row row, T vo, Field field, int column)` 添加单元格数据到指定行和列。
`void`	`addStatisticsRow()` 创建统计行并添加到当前工作表的末尾。
`static String`	`convertByExp(String propertyValue, String converterExp, String separator)` 根据表达式将属性值转换为对应的显示值。
`org.apache.poi.ss.usermodel.Cell`	`createCell(Excel attr, org.apache.poi.ss.usermodel.Row row, int column)` 创建单元格并设置表头样式。
`void`	`createSheet(int sheetNo, int index)` 创建工作表在需要多个 sheet 时（sheetNo 大于 1），并且当前是第 2 个及以后的 sheet（index 大于 0）为工作簿创建一个新工作表，设置表头标题，并将该 sheet 命名为 sheetName+index 这样可以实现多 sheet 导出时，每个 sheet 都有独立的标题和名称。
`void`	`createTitle()` 创建 Excel 的标题行（第一行）。
`void`	`createWorkbook()` 创建一个工作簿
`String`	`dataFormatHandlerAdapter(Object value, Excel excel)` 使用自定义数据处理器格式化单元格数据。
`void`	`exportExcel(jakarta.servlet.http.HttpServletResponse response)` 将当前工作簿内容写入 HTTP 响应流，实现 Excel 文件导出。
`void`	`exportExcel(jakarta.servlet.http.HttpServletResponse response, List<T> list, String sheetName)` 导出数据到 Excel 文件。
`void`	`exportExcel(jakarta.servlet.http.HttpServletResponse response, List<T> list, String sheetName, String title)` 导出数据到 Excel 文件，并设置标题。
`void`	`fillExcelData(int index, org.apache.poi.ss.usermodel.Row row)` 填充 Excel 数据到当前 Sheet。
`Object`	`getCellValue(org.apache.poi.ss.usermodel.Row row, int column)` 获取指定行和列的单元格值，并根据单元格类型进行转换。
`static org.apache.poi.ss.usermodel.Drawing<?>`	`getDrawingPatriarch(org.apache.poi.ss.usermodel.Sheet sheet)` 获取或创建指定 Sheet 的画布对象（Drawing）。
`List<Object[]>`	`getFields()` 获取类中所有带有 @Excel 或 @Excels 注解的字段信息。
`int`	`getImageType(byte[] value)` 根据图片字节内容判断图片类型，返回 POI 对应的图片类型常量。
`short`	`getRowHeight()` 根据注解获取最大行高
`List<T>`	`importExcel(InputStream is)` 将 Excel 数据导入为对象列表。
`List<T>`	`importExcel(InputStream is, int titleNum)` 将 Excel 数据导入为对象列表。
`List<T>`	`importExcel(String sheetName, InputStream is, int titleNum)` 将 Excel 数据导入为对象列表。
`void`	`importTemplateExcel(jakarta.servlet.http.HttpServletResponse response, String sheetName)` 对list数据源将其里面的数据导入到excel表单
`void`	`importTemplateExcel(jakarta.servlet.http.HttpServletResponse response, String sheetName, String title)` 对list数据源将其里面的数据导入到excel表单
`void`	`init(List<T> list, String sheetName, String title, TypeEnum type)` 初始化 Excel 工具类，设置数据源、工作表名称、标题和导出类型。
`String`	`parseDateToStr(String dateFormat, Object val)` 根据指定格式将不同类型的日期对象格式化为字符串。
`static String`	`reverseByExp(String propertyValue, String converterExp, String separator)` 根据表达式将显示值反向转换为属性值。
`void`	`setCellVo(Object value, Excel attr, org.apache.poi.ss.usermodel.Cell cell)` 设置单元格的值和样式。
`void`	`setDataCell(org.apache.poi.ss.usermodel.Cell cell, Excel excel)` 设置单元格的样式。
`void`	`setDataValidation(Excel attr, org.apache.poi.ss.usermodel.Row row, int column)` 设置单元格的数据校验和列宽。
`void`	`setPromptOrValidation(org.apache.poi.ss.usermodel.Sheet sheet, String[] textlist, String promptContent, int firstRow, int endRow, int firstCol, int endCol)` 为指定的 Excel 区域设置单元格下拉框或提示框数据校验。
`void`	`writeSheet()` 写入数据到 Excel 工作表。

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - FORMULA_REGEX_STR
```
public static final String FORMULA_REGEX_STR
```
    See Also:
    
    Constant Field Values
  - FORMULA_STR
```
public static final String[] FORMULA_STR
```
  - sheetSize
```
public static final int sheetSize
```
    Excel sheet最大行数，默认65536
    
    See Also:
    
    Constant Field Values
  - clazz
```
public Class<T> clazz
```
    实体对象
- Constructor Detail
  - ExcelUtils
```
public ExcelUtils(Class<T> clazz)
```
    构造方法，初始化工具类
    
    Parameters:
    
    clazz - 实体类类型
- Method Detail
  - init
```
public void init(List<T> list,
                 String sheetName,
                 String title,
                 TypeEnum type)
```
    初始化 Excel 工具类，设置数据源、工作表名称、标题和导出类型。
    - 如果数据源为空，则初始化为空列表
    - 根据类的字段创建 Excel 字段映射
    - 创建工作簿和标题
    Parameters:
    
    list - 数据源
    
    sheetName - 工作表名称
    
    title - 标题
    
    type - 导出类型（EXPORT 或 IMPORT）
  - createTitle
```
public void createTitle()
```
    创建 Excel 的标题行（第一行）。
    - 如果设置了标题（title 不为空），则在第一行创建标题单元格，并合并单元格区域。
    - 设置标题行的高度和样式。
    - 合并单元格范围为：第 0 行到第 0 行，第 0 列到最后一列。
  - importExcel
```
public List<T> importExcel(InputStream is)
                    throws Exception
```
    将 Excel 数据导入为对象列表。
    - 默认读取第一个工作表，标题占用一行
    - 根据 Excel 注解自动映射字段
    Parameters:
    
    is - 输入流
    
    Returns:
    
    转换后的对象列表
    
    Throws:
    
    Exception - 如果解析失败
  - importExcel
```
public List<T> importExcel(InputStream is,
                           int titleNum)
                    throws Exception
```
    将 Excel 数据导入为对象列表。
    - 可指定标题占用的行数（titleNum），从指定行数后开始读取数据
    - 根据 Excel 注解自动映射字段
    Parameters:
    
    is - 输入流
    
    titleNum - 标题占用行数
    
    Returns:
    
    转换后的对象列表
    
    Throws:
    
    Exception - 如果解析失败
  - importExcel
```
public List<T> importExcel(String sheetName,
                           InputStream is,
                           int titleNum)
                    throws Exception
```
    将 Excel 数据导入为对象列表。
    - 可指定工作表名称（sheetName）和标题占用的行数（titleNum）
    - 从指定的 sheet 和标题行后开始读取数据
    - 根据 @Excel 注解自动映射字段
    Parameters:
    
    sheetName - 工作表名称
    
    is - 输入流
    
    titleNum - 标题占用行数
    
    Returns:
    
    转换后的对象列表
    
    Throws:
    
    Exception - 如果解析失败
  - exportExcel
```
public void exportExcel(jakarta.servlet.http.HttpServletResponse response,
                        List<T> list,
                        String sheetName)
```
    导出数据到 Excel 文件。
    - 初始化 Excel 工具类，设置数据源、工作表名称和导出类型
    - 将生成的 Excel 文件写入 HTTP 响应流，供客户端下载
    Parameters:
    
    response - HTTP 响应对象
    
    list - 数据源
    
    sheetName - 工作表名称
  - exportExcel
```
public void exportExcel(jakarta.servlet.http.HttpServletResponse response,
                        List<T> list,
                        String sheetName,
                        String title)
```
    导出数据到 Excel 文件，并设置标题。
    - 初始化 Excel 工具类，设置数据源、工作表名称、标题和导出类型
    - 将生成的 Excel 文件写入 HTTP 响应流，供客户端下载
    Parameters:
    
    response - HTTP 响应对象
    
    list - 数据源
    
    sheetName - 工作表名称
    
    title - 标题
  - importTemplateExcel
```
public void importTemplateExcel(jakarta.servlet.http.HttpServletResponse response,
                                String sheetName)
```
    对list数据源将其里面的数据导入到excel表单
    
    Parameters:
    
    response - HTTP 响应对象
    
    sheetName - 工作表名称
  - importTemplateExcel
```
public void importTemplateExcel(jakarta.servlet.http.HttpServletResponse response,
                                String sheetName,
                                String title)
```
    对list数据源将其里面的数据导入到excel表单
    
    Parameters:
    
    response - HTTP 响应对象
    
    sheetName - 工作表名称
    
    title - 标题
  - exportExcel
```
public void exportExcel(jakarta.servlet.http.HttpServletResponse response)
```
    将当前工作簿内容写入 HTTP 响应流，实现 Excel 文件导出。
    - 写入数据到 sheet
    - 将生成的 Excel 文件写入响应流，供客户端下载
    - 异常时记录日志
    - 最后关闭工作簿资源
    Parameters:
    
    response - HTTP 响应对象
  - writeSheet
```
public void writeSheet()
```
    写入数据到 Excel 工作表。
    - 根据数据量动态创建多个 Sheet，每个 Sheet 填充部分数据。
    - 为每个 Sheet 创建表头行并写入字段名称。
    - 如果为导出模式（EXPORT），则填充数据和统计行。
  - fillExcelData
```
public void fillExcelData(int index,
                          org.apache.poi.ss.usermodel.Row row)
```
    填充 Excel 数据到当前 Sheet。
    - 根据 sheet 索引计算数据起止位置，分批写入数据。
    - 为每一行创建单元格，并根据字段注解设置值和样式。
    - 每个字段调用 addCell 方法写入单元格内容。
    Parameters:
    
    index - 当前 Sheet 的索引
    
    row - 当前表头行对象
  - createCell
```
public org.apache.poi.ss.usermodel.Cell createCell(Excel attr,
                                                   org.apache.poi.ss.usermodel.Row row,
                                                   int column)
```
    创建单元格并设置表头样式。
    - 根据 @Excel 注解设置单元格的列名、样式和数据校验。
    - 为表头行创建单元格，并应用 header 样式。
    - 如有下拉选项或提示信息，则为该列添加数据校验。
    Parameters:
    
    attr - Excel 注解
    
    row - 行对象
    
    column - 列索引
    
    Returns:
    
    创建的单元格对象
  - setCellVo
```
public void setCellVo(Object value,
                      Excel attr,
                      org.apache.poi.ss.usermodel.Cell cell)
```
    设置单元格的值和样式。
    - 字符串类型：防止CSV注入，支持默认值和后缀
    - 数字类型：根据内容设置为整数或小数
    - 图片类型：插入图片到单元格
    Parameters:
    
    value - 单元格值
    
    attr - Excel注解
    
    cell - 单元格对象
  - getDrawingPatriarch
```
public static org.apache.poi.ss.usermodel.Drawing<?> getDrawingPatriarch(org.apache.poi.ss.usermodel.Sheet sheet)
```
    获取或创建指定 Sheet 的画布对象（Drawing）。
    - 如果当前 Sheet 尚未存在画布，则创建一个新的画布并返回
    - 如果已存在画布，则直接返回该画布
    - 画布用于插入图片、图形等对象
    Parameters:
    
    sheet - 工作表对象
    
    Returns:
    
    画布对象（Drawing）
  - getImageType
```
public int getImageType(byte[] value)
```
    根据图片字节内容判断图片类型，返回 POI 对应的图片类型常量。
    - JPG 类型返回 Workbook.PICTURE_TYPE_JPEG
    - PNG 类型返回 Workbook.PICTURE_TYPE_PNG
    - 其他类型默认返回 JPEG
    Parameters:
    
    value - 图片字节数组
    
    Returns:
    
    POI 图片类型常量
  - setDataValidation
```
public void setDataValidation(Excel attr,
                              org.apache.poi.ss.usermodel.Row row,
                              int column)
```
    设置单元格的数据校验和列宽。
    - 如果列名包含“注：”，设置固定宽度
    - 否则根据注解配置设置列宽
    - 如有下拉选项或提示信息，则为该列添加下拉框或提示框
    Parameters:
    
    attr - Excel注解
    
    row - 行对象
    
    column - 列索引
  - addCell
```
public org.apache.poi.ss.usermodel.Cell addCell(Excel attr,
                                                org.apache.poi.ss.usermodel.Row row,
                                                T vo,
                                                Field field,
                                                int column)
```
    添加单元格数据到指定行和列。
    - 根据 @Excel 注解配置设置单元格值和格式
    - 支持日期、表达式转换、自定义处理器、BigDecimal 精度等
    - 根据注解决定是否导出该列
    - 支持统计行数据累加
    Parameters:
    
    attr - Excel 注解
    
    row - 行对象
    
    vo - 数据对象
    
    field - 字段对象
    
    column - 列索引
    
    Returns:
    
    创建的单元格对象
  - setDataCell
```
public void setDataCell(org.apache.poi.ss.usermodel.Cell cell,
                        Excel excel)
```
    设置单元格的样式。
    - 根据 @Excel 注解配置对齐方式、字体、边框和字体颜色等样式属性
    - 应用于数据单元格，确保导出 Excel 时格式统一
    Parameters:
    
    cell - 单元格对象
    
    excel - Excel 注解信息
  - setPromptOrValidation
```
public void setPromptOrValidation(org.apache.poi.ss.usermodel.Sheet sheet,
                                  String[] textlist,
                                  String promptContent,
                                  int firstRow,
                                  int endRow,
                                  int firstCol,
                                  int endCol)
```
    为指定的 Excel 区域设置单元格下拉框或提示框数据校验。
    - 如果 textlist 非空，则为单元格添加下拉选项。
    - 如果 promptContent 非空，则为单元格添加鼠标悬停提示。
    - 支持设置起止行列范围。
    - 自动处理 XSSF 兼容性问题。
    Parameters:
    
    sheet - 工作表对象
    
    textlist - 下拉框选项内容数组
    
    promptContent - 提示内容
    
    firstRow - 起始行
    
    endRow - 结束行
    
    firstCol - 起始列
    
    endCol - 结束列
  - convertByExp
```
public static String convertByExp(String propertyValue,
                                  String converterExp,
                                  String separator)
```
    根据表达式将属性值转换为对应的显示值。
    - 支持多值分隔（如 1,2 转换为男,女）
    - 表达式格式如：0=男,1=女,2=未知
    - 单值直接匹配返回，分隔符存在时遍历匹配所有值
    Parameters:
    
    propertyValue - 属性值
    
    converterExp - 转换表达式（如 0=男,1=女）
    
    separator - 多值分隔符
    
    Returns:
    
    转换后的显示值
  - reverseByExp
```
public static String reverseByExp(String propertyValue,
                                  String converterExp,
                                  String separator)
```
    根据表达式将显示值反向转换为属性值。
    - 支持多值分隔（如男,女转换为 1,2）
    - 表达式格式如：0=男,1=女,2=未知
    - 单值直接匹配返回，分隔符存在时遍历匹配所有值
    Parameters:
    
    propertyValue - 显示值
    
    converterExp - 转换表达式（如 0=男,1=女）
    
    separator - 多值分隔符
    
    Returns:
    
    反向转换后的属性值
  - dataFormatHandlerAdapter
```
public String dataFormatHandlerAdapter(Object value,
                                       Excel excel)
```
    使用自定义数据处理器格式化单元格数据。
    - 通过 @Excel 注解指定的 handler 类，对数据进行自定义格式化处理
    - 调用 handler 的 format 方法，传入原始值和参数数组
    - 格式化失败时记录日志，返回字符串类型的结果
    Parameters:
    
    value - 原始数据值
    
    excel - Excel 注解信息（包含 handler 和参数）
    
    Returns:
    
    格式化后的字符串结果
  - addStatisticsRow
```
public void addStatisticsRow()
```
    创建统计行并添加到当前工作表的末尾。
    - 如果存在需要统计的列，则在表格末尾新增一行“合计”
    - 将所有已统计的列的总和写入对应单元格
    - 写入后清空统计数据
  - getFields
```
public List<Object[]> getFields()
```
    获取类中所有带有 @Excel 或 @Excels 注解的字段信息。
    - 遍历父类和当前类的所有字段
    - 收集符合导入/导出类型的注解字段
    - 支持单个 @Excel 注解和多个 @Excel 注解（@Excels）
    - 返回字段和注解对象的数组列表
    Returns:
    
    字段和注解对象的列表，每项为 Object[]{Field, Excel}
  - getRowHeight
```
public short getRowHeight()
```
    根据注解获取最大行高
    
    Returns:
    
    最大行高度
  - createWorkbook
```
public void createWorkbook()
```
    创建一个工作簿
  - createSheet
```
public void createSheet(int sheetNo,
                        int index)
```
    创建工作表在需要多个 sheet 时（sheetNo 大于 1），并且当前是第 2 个及以后的 sheet（index 大于 0）为工作簿创建一个新工作表，设置表头标题，并将该 sheet 命名为 sheetName+index 这样可以实现多 sheet 导出时，每个 sheet 都有独立的标题和名称。
    
    Parameters:
    
    sheetNo - sheet数量
    
    index - 序号
  - getCellValue
```
public Object getCellValue(org.apache.poi.ss.usermodel.Row row,
                           int column)
```
    获取指定行和列的单元格值，并根据单元格类型进行转换。
    - 数值或公式类型：如为日期格式则转为 Date，否则按数字或整数处理
    - 字符串类型：返回字符串
    - 布尔类型：返回 boolean
    - 错误类型：返回错误码
    - 单元格为 null：返回空字符串
    Parameters:
    
    row - 行对象
    
    column - 列号
    
    Returns:
    
    单元格的值（Object 类型）
  - parseDateToStr
```
public String parseDateToStr(String dateFormat,
                             Object val)
```
    根据指定格式将不同类型的日期对象格式化为字符串。支持 Date、LocalDateTime、LocalDate 类型，其他类型则直接调用 toString()。
    - val 为 null 时，返回空字符串
    - val 为 Date 类型，直接格式化
    - val 为 LocalDateTime 或 LocalDate 类型，先转为 Date 再格式化
    - 其他类型，直接转为字符串
    Parameters:
    
    dateFormat - 日期格式字符串
    
    val - 需要格式化的日期对象
    
    Returns:
    
    格式化后的日期字符串

Class ExcelUtils<T>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

FORMULA_REGEX_STR

FORMULA_STR

sheetSize

clazz

Constructor Detail

ExcelUtils

Method Detail

init

createTitle

importExcel

importExcel

importExcel

exportExcel

exportExcel

importTemplateExcel

importTemplateExcel

exportExcel

writeSheet

fillExcelData

createCell

setCellVo

getDrawingPatriarch

getImageType

setDataValidation

addCell

setDataCell

setPromptOrValidation

convertByExp

reverseByExp

dataFormatHandlerAdapter

addStatisticsRow

getFields

getRowHeight

createWorkbook

createSheet

getCellValue

parseDateToStr