ContiNew

切换日光/暗黑模式

POI ​

最后更新: 4 天前
实践版本: v2.16.0
提示文档具有版本时效性，部分内容可能已不适用于当前版本。如发现过时内容，请联系作者进行更新。

简介 ​

continew-starter-excel-poi 是 ContiNew Starter Excel 文件处理模块基于 Apache POI 的实现（@since 2.13.0），提供 Excel 导入导出工具类，支持模板导出、下拉列表、行列合并、图片导出及导入校验回填等能力，无任何 Spring 自动配置（纯工具类模块）。

主要特性 ​

  • 功能全面： 模板导出、下拉列表校验、URL 图片导出、行/列合并
  • 导入校验： 必填、最大长度、kv 映射、多字段联合唯一校验，错误信息自动回填
  • 双格式： 支持 .xlsx / .xls 读取，SXSSF 流式导出降低内存占用
  • 零配置： 无自动配置与配置属性，引入即用工具类

与 FastExcel 不可同时引入

本模块与 FastExcel 提供的 ExcelUtils 同名同包（top.continew.starter.excel.util.ExcelUtils）但 API 体系完全独立，同时引入会产生类冲突，请按需二选一。

使用方式 ​

引入依赖 ​

pom.xml
xml
<dependency>
    <groupId>top.continew.starter</groupId>
    <artifactId>continew-starter-excel-poi</artifactId>
</dependency>

实体注解 ​

在实体字段上标注 @ExcelExport / @ExcelImport 注解（由 continew-starter-excel-core 提供）：

java
@Data
public class UserExcel {

    @ExcelExport(value = "用户名", sort = 1)
    @ExcelImport(value = "用户名", required = true)
    private String username;

    @ExcelExport(value = "状态", kv = "1-正常;2-禁用", sort = 2)
    @ExcelImport(value = "状态", kv = "1-正常;2-禁用")
    private Integer status;
}

注解属性：value（字段名称）、sort（导出排序，越小越靠前）、kv（值映射，格式如 0-未知;1-男;2-女）、example（导出示例）；导入侧另有 required（必填）、maxLength（最大长度，默认 255）、unique（多字段联合唯一校验）。

导入 ​

java
// 读取文件为实体列表（.xlsx / .xls 均可，也支持 readMultipartFile）
List<UserExcel> list = ExcelUtils.readFile(file, UserExcel.class);
// 实体中名为 rowNum / rowTips / rowData 的字段分别承载行号、错误信息、原始数据

导出 ​

ExcelUtils 提供 export（按实体列表或模板导出，支持自定义 sheet 名、下拉列表 Map<Integer, List<String>>）、exportTemplate（导出模板，可选示例行）、exportManySheet、exportFile、exportEmpty 等静态方法，完整签名详见源码 top.continew.starter.excel.util.ExcelUtils。

单元格值填入 ROW_MERGE / COLUMN_MERGE 常量字符串可触发行/列合并；kv 映射字段导出时自动转为下拉列表。

核心依赖 ​

依赖描述
top.continew.starter:continew-starter-excel-coreExcel 文件处理模块 - 核心模块（@ExcelImport/@ExcelExport 注解）
org.apache.poi:poi-ooxmlApache POI（适用于 Microsoft 文档的 Java API）

参考资料 ​

  1. Apache POI 官方文档：https://poi.apache.org/
  2. ContiNew Starter FastExcel 模块