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 支持！

相关推荐
掘金者阿豪7 分钟前
记一次NFS下的权限踩坑：从“Operation not permitted”到安装成功的折腾实录
后端
妙蛙种子31110 分钟前
【Java设计模式 | 创建者模式】 原型模式
java·开发语言·后端·设计模式·原型模式
阿聪谈架构17 分钟前
第07章（下）：LangGraph 工作流进阶 —— 检查点、人工介入与多 Agent 协作
人工智能·后端
希望永不加班22 分钟前
SpringBoot 配置绑定：@ConfigurationProperties
java·spring boot·后端·spring
悟空码字23 分钟前
MySQL性能优化的天花板：10条你必须掌握的顶级SQL分析技巧
java·后端·mysql
Soofjan27 分钟前
Go interface 源码：iface、itab、getitab 与动态派发
后端
Soofjan29 分钟前
Go interface：语法、接口值与常见坑
后端
写Cpp的小黑黑30 分钟前
WebSocket 协议、帧结构与 MTU 详解
后端
white-persist35 分钟前
【vulhub spring CVE-2018-1270】CVE-2018-1270 Spring Messaging 远程命令执行漏洞 完整复现详细分析解释
java·服务器·网络·数据库·后端·python·spring
神奇小汤圆1 小时前
Spring-Boot-泛型封装-这8个坑让我调了3天
后端
热门推荐
01一周AI热点速览（2026.03.31-04.06）：GPT-6曝光、谷歌开源Gemma 4、资本狂飙与模型军备竞赛022026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元03GitHub 镜像站点04基于 Docker 部署 Hermes Agent 并接入飞书机器人的完整指南05AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析06免费！不限量！用opencode接入英伟达（NVIDIA）大模型，轻松打造你的 AI 编程助手07Oh My Codex 快速使用指南08VMware Workstation Pro 17 虚拟机完整安装教程（2026最新）09CodeBuddy与WorkBuddy深度对比：腾讯两款AI工具差异及实操指南10OpenClaw 请求超时 llm request timed out 怎么解决？3 种方案实测，附完整排查流程