jquickexcel 全功能指南：从数据导入到精美导出的完整流程

泡海椒2025-08-12 16:33

jquickexcel 作为一款高效的 Java Excel 处理工具，不仅简化了导出流程，更在数据导入环节提供了全面支持。本文将按照「导入 - 导出」全流程，详细介绍各核心功能的具体用法，助你轻松应对各类 Excel 处理场景。

一、导入功能：从 Excel 到数据对象的无缝转换

1. 环境准备：快速安装依赖

Maven 配置：

xml

xml 复制代码 
<dependency>
    <groupId>io.github.paohaijiao</groupId>
    <artifactId>jquick-excel</artifactId>
    <version>1.3.0</version> <!-- 使用最新版本 -->
</dependency>

Gradle 配置：

groovy

arduino 复制代码 
implementation 'io.github.paohaijiao:jquick-excel:1.3.0'

2. 字段映射：Excel 列与实体类的绑定

导入时首先需要解决「Excel 列标题」与「Java 实体类字段」的对应关系，jquickexcel 提供两种映射方式：

方式一：字段映射

java

ini 复制代码 
IMPORT WITH HEADER=true,MAPPING = {
    "学号": "no",
    "姓名": "name",
    "性别": "sex",
    "年龄": "age",
    "出生日期": "birthday"
}



        JQuickExcelCommonImportExecutor executor=new JQuickExcelCommonImportExecutor();
        JExcelImportModel model= (JExcelImportModel)executor.execute(rule);
        InputStream is = JMappingTest.class.getClassLoader().getResourceAsStream("templates/student.xlsx");
        XSSFWorkbook workbook=new XSSFWorkbook(is);
        JExcelImportHandler handler=new JExcelImportHandler(workbook);
        List<Map<String, Object>> list= handler.importData(model);

方式二：字段转换（动态场景）

ini 复制代码 
IMPORT WITH HEADER=true,SHEET='Sheet1',MAPPING = {
"学号": "no",
"姓名": "name",
"性别": "sex",
"年龄": "age",
"出生日期": "birthday"
},TRANSFORM={"sex":trans(${dict},${sex})"birthday":dateFormat(${birthday},'yyyy-MM-dd')}

     JQuickExcelCommonImportExecutor executor=new JQuickExcelCommonImportExecutor();
        JExcelImportModel model= (JExcelImportModel)executor.execute(rule);
        InputStream is = JMappingTest.class.getClassLoader().getResourceAsStream("templates/student.xlsx");
        XSSFWorkbook workbook=new XSSFWorkbook(is);
        Map<String,Object> sex=new HashMap<>();
        sex.put("男","1");
        sex.put("女","2");
        JContext context = new JContext();
        context.put("dict",sex);
        JExcelImportHandler handler=new JExcelImportHandler(workbook,context);
        List<Map<String, Object>> list= handler.importData(model);

3. 导入数据验证

示例 1：日期格式转换

dart 复制代码 
IMPORT WITH VALIDATION={
    ROW 1..10 {
        required {required: true, msg: "error1"},
        range {required: true, msg: "error2", map: {min: 1, max: 100}}
    },
    COL A {
        required {required: true, msg: "error3"}
    },
    B1:C5 {
        regex {required: true, msg: "error4", map: {pattern: "^\\d+$"}}
    }
}

 HashMap<String,Object> map = new HashMap<>();
        map.put("1","男");
        map.put("2","女");
        JQuickExcelCommonImportExecutor executor=new JQuickExcelCommonImportExecutor();
        JExcelImportModel model= (JExcelImportModel)executor.execute(input);
        InputStream is = JMappingTest.class.getClassLoader().getResourceAsStream("templates/student.xlsx");
        XSSFWorkbook workbook=new XSSFWorkbook(is);
        JExcelImportHandler handler=new JExcelImportHandler(workbook);
        List<Map<String, Object>> list= handler.importData(model);

二、导出功能：从数据到精美报表的一站式解决方案

1. 格式化：统一数据展示格式

通过格式化配置，让日期、数字等类型数据以规范格式呈现：

ini 复制代码 
EXPORT  WITH
SHEET="学生表",
HEADER=true,
MAPPING={
	"id":"主键",
	"name":"姓名",
	"gender":"性别",
	"age":"年龄",
	"enrollmentDate":"入学时间",
	"className":"班级",
	"ignoreField":"是否忽略"
},FORMAT={"enrollmentDate":"yyyy-MM-dd"}

    List<Map<String, Object>> data = JObjectConverter.convert(getData());
        FileOutputStream fileOutputStream=new FileOutputStream("d://test//format.xlsx");
        JQuickExcelCommonExportExecutor executor = new JQuickExcelCommonExportExecutor();
        JExcelExportModel config = (JExcelExportModel) executor.execute(input);
        JExcelExportHandler handler = new JExcelExportHandler(config,data);
        Workbook workbook=handler.getWorkBook();
        workbook.write(fileOutputStream);

2. 字段映射：自定义导出列名与顺序

灵活控制导出的列顺序和显示名称，无需修改实体类：

typescript 复制代码 
EXPORT  WITH
SHEET="学生表",
HEADER=true,
MAPPING={
	"id":"主键",
	"name":"姓名",
	"gender":"性别",
	"age":"年龄",
	"enrollmentDate":"入学时间",
	"className":"班级",
	"ignoreField":"是否忽略"
}

    public static List<JStudentModel> getData() {
        List<JStudentModel> students = new ArrayList<>();
        students.add(new JStudentModel("1001", "张三", 1, 20, new Date(), "计算机1班", "true"));
        students.add(new JStudentModel("1002", "李四", 0, 21, new Date(), "计算机2班", "true"));
        students.add(new JStudentModel("1003", "王五", 1, 22, new Date(), "计算机3班", "true"));
        return students;
    }
        List<Map<String, Object>> data = JObjectConverter.convert(getData());
        FileOutputStream fileOutputStream=new FileOutputStream("d://test//format.xlsx");
        JQuickExcelCommonExportExecutor executor = new JQuickExcelCommonExportExecutor();
        JExcelExportModel config = (JExcelExportModel) executor.execute(input);
        JExcelExportHandler handler = new JExcelExportHandler(config,data);
        Workbook workbook=handler.getWorkBook();
        workbook.write(fileOutputStream);

3. 数据转换：让导出数据更易读

将存储的编码转换为用户友好的文本，如将状态码转换为状态名称：

ini 复制代码 
EXPORT  WITH
SHEET="学生表",
HEADER=true,
MAPPING={
	"id":"主键",
	"name":"姓名",
	"gender":"性别",
	"age":"年龄",
	"enrollmentDate":"入学时间",
	"className":"班级",
	"ignoreField":"是否忽略"
},FORMAT={	"enrollmentDate":"yyyy-MM-dd"
},

TRANSFORM={
"name": toUpper(${name}),
"enrollmentDate": dateFormat(${enrollmentDate},'yyyy-MM-dd'),
"gender": trans(${dict},${gender})
}

   List<Map<String, Object>> data = JObjectConverter.convert(getData());
        FileOutputStream fileOutputStream=new FileOutputStream("d://test//transform.xlsx");
        JQuickExcelCommonExportExecutor executor = new JQuickExcelCommonExportExecutor();
        JExcelExportModel config = (JExcelExportModel) executor.execute(input);
        HashMap<String,Object> map = new HashMap<>();
        map.put("1","男");
        map.put("0","女");
        JContext context = new JContext();
        context.put("dict",map);
        JExcelExportHandler handler = new JExcelExportHandler(config,context,data);
        Workbook workbook=handler.getWorkBook();
        workbook.write(fileOutputStream);

4. Excel 公式：自动计算统计数据

直接在导出时配置公式，避免手动计算：

makefile 复制代码 
EXPORT  WITH
SHEET="学生表",
HEADER=true,
MAPPING={
"id":"主键",
"name":"姓名",
"gender":"性别",
"age":"年龄",
"enrollmentDate":"入学时间",
"className":"班级",
"ignoreField":"是否忽略"
},
FORMULAS={
D5:'ABS(D2)'
}

5. 样式美化：打造专业报表外观

通过样式配置美化 Excel，支持字体、颜色、对齐方式等设置：

ini 复制代码 
EXPORT  WITH
SHEET="学生表",
HEADER=true,
MAPPING={
	"id":"主键",
	"name":"姓名",
	"gender":"性别",
	"age":"年龄",
	"enrollmentDate":"入学时间",
	"className":"班级",
	"ignoreField":"是否忽略"
},
FORMULAS={
D5:'ABS(D2)'},  STYLE={
    ROW 1: {
      fontName: Arial,
      fontHeightInPoints: 12,
      italic: true,
      color: yellow,
      bold: true
    }}

      List<Map<String, Object>> data = JObjectConverter.convert(getData());
        FileOutputStream fileOutputStream=new FileOutputStream("d://test//style.xlsx");
        JQuickExcelCommonExportExecutor executor = new JQuickExcelCommonExportExecutor();
        JExcelExportModel config = (JExcelExportModel) executor.execute(rule);
        HashMap<String,Object> map = new HashMap<>();
        map.put("1","男");
        map.put("0","女");
        JContext context = new JContext();
        context.put("dict",map);
        JExcelExportHandler handler = new JExcelExportHandler(config,context,data);
        Workbook workbook=handler.getWorkBook();
        workbook.write(fileOutputStream);

6. 单元格合并：制作汇总报表

支持按规则合并单元格，适合制作分组汇总报表：

ini 复制代码 
EXPORT WITH MERGE: {
    ROWS 1 WITH MERGE_WITH_MAX,  
    ROWS 2..3 WITH MERGE_WITH_MIN
 }


 public static List<JDataModel> getData() {
        List<JDataModel> students = new ArrayList<>();
        students.add(new JDataModel(1, 22, 3, 4, 5, 6, 1));
        students.add(new JDataModel(2, 0, 1, 1, 1, 1, 1));
        students.add(new JDataModel(3, -1, 1, 1, 1, 1, 1));
        students.add(new JDataModel(4, 1, 1, 1, 1, 1, 1));
        students.add(new JDataModel(5, 1, 1, 1, 1, 1, 1));
        students.add(new JDataModel(6, 1, 1, 1, 1, 1, 1));
        students.add(new JDataModel(7, 1, 1, 1, 1, 1, 1));
        students.add(new JDataModel(8, 1, 1, 1, 1, 1, 1));
        students.add(new JDataModel(9, 1, 1, 1, 1, 1, 1));
        students.add(new JDataModel(10, 1, 1, 1, 1, 1, 1));
        students.add(new JDataModel(11, 1, 1, 1, 1, 1, 1));
        students.add(new JDataModel(12, 1, 1, 1, 1, 1, 1));
        students.add(new JDataModel(13, 1, 1, 1, 1, 1, 1));
        students.add(new JDataModel(14, 1, 1, 1, 1, 1, 1));
        return students;
    }
    @Test
    public void max() throws IOException {
        String rule = "EXPORT WITH MERGE: {\n" +
                "    ROWS 1 WITH MERGE_WITH_MAX,"+
                "    ROWS 2..3 WITH MERGE_WITH_MIN"+
                "}";
        System.out.println(rule);
        List<Map<String, Object>> data = JObjectConverter.convert(getData());
        FileOutputStream fileOutputStream=new FileOutputStream("d://test//merge.xlsx");
        JQuickExcelCommonExportExecutor executor = new JQuickExcelCommonExportExecutor();
        JExcelExportModel config = (JExcelExportModel) executor.execute(rule);
        HashMap<String,Object> map = new HashMap<>();
        map.put("1","男");
        map.put("0","女");
        JContext context = new JContext();
        context.put("dict",map);
        JExcelExportHandler handler = new JExcelExportHandler(config,context,data);
        Workbook workbook=handler.getWorkBook();
        workbook.write(fileOutputStream);
    }

7. 图表生成：数据可视化一键完成

直接在导出时生成图表，支持多种图表类型：

ini 复制代码 
EXPORT WITH GRAPH = {
    TYPE = COLUMN,
    TITLE = "销售数据统计",
    CATEGORY_AXIS = "产品",
    VALUE_AXIS = "销量",
    CATEGORIES = ["产品A", "产品B", "产品C", "产品D"],
    SERIES = [{
        NAME = "第一季度",
        DATA = [120, 200, 150, 180]
    }, {
        NAME = "第二季度",
        DATA = [180, 210, 190, 220]
    }]
}


    JChartData chartData = new JChartData();
        chartData.setTitle("销售数据统计");
        chartData.setCategoryAxisTitle("产品");
        chartData.setValueAxisTitle("销量");
        chartData.setCategories(Arrays.asList("产品A", "产品B", "产品C", "产品D"));
        JSeriesData series1 = new JSeriesData();
        series1.setName("第一季度");
        series1.setData(Arrays.asList(120, 200, 150, 180));
        JSeriesData series2 = new JSeriesData();
        series2.setName("第二季度");
        series2.setData(Arrays.asList(180, 210, 190, 220));
        chartData.setSeries(Arrays.asList(series1, series2));
        XSSFWorkbook workbook = JExcelChartFactory.createWorkbookWithChart(
                chartData, JExcelChartType.COLUMN, "销售报表");
        try (FileOutputStream out = new FileOutputStream("D://test//SalesReport.xlsx")) {
            JExcelChartFactory.writeWorkbookToStream(workbook, out);
        } catch (IOException e) {
            e.printStackTrace();
        }

8. 页脚设置：添加页码与版权信息

为报表添加页脚，支持动态页码和固定文本：

ini 复制代码 
EXPORT WITH FOOTER="Generated by JQuickExcel on ${current_date()}"

总结

jquickexcel 通过「注解 + 规则配置」的双重方式，实现了 Excel 处理的全场景覆盖。无论是简单的数据导入导出，还是复杂的报表生成，都能通过简洁的代码完成。其底层基于 POI 但又简化了 80% 的冗余代码，让开发者从繁琐的 Excel 操作中解放出来。

更多高级用法和示例代码，请参考官方文档：github.com/paohaijiao/...，如果觉得好用，欢迎给项目点个 Star 支持！

相关推荐
Pr Young4 小时前
服务优雅停止和服务优雅启动
后端
嘟嘟MD5 小时前
程序员副业 | 2025年9月复盘
后端·aigc
尘觉5 小时前
中秋节与 Spring Boot 的思考：一场开箱即用的团圆盛宴
java·spring boot·后端
间彧6 小时前
Seata分布式事务框架详解与项目实战
后端
zhuyasen6 小时前
单机已达上限？PerfTest 分布式压测登场，轻松模拟百万用户洪峰
后端·性能优化·测试
勇哥java实战分享6 小时前
sensitive-word：一个简单易用的敏感词过滤框架
后端
popoxf6 小时前
spring容器启动流程（反射视角）
java·后端·spring
Funcy7 小时前
XxlJob 源码08：任务执行流程（三）之执行器揭秘
后端
AAA修煤气灶刘哥7 小时前
监控摄像头？不，我们管这个叫优雅的埋点艺术！
java·后端·spring cloud
2301_772093567 小时前
tuchuang_后端_前端_注册登录
数据库·后端·网络协议·mysql·wireshark
热门推荐
01KGG转MP3工具|非KGM文件|解密音频02GitHub 镜像站点03PHP htmlspecialchars()函数详解04UV安装并设置国内源05两千字总结：Codex 国内如何安装和使用的教程，以及如何设置中文回答06Linux下V2Ray安装配置指南07BongoCat - 跨平台键盘猫动画工具08jdk21下载、安装（Windows、Linux、macOS）0946个Nano-banana 精选提示词，持续更新中10零基础搭建赛博朋克个人主页：蓝耘Claude Code完整实战教程