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

相关推荐
Moonbit1 小时前
MoonBit 作者寄语 2025 级清华深圳新生
前端·后端·程序员
前端的阶梯1 小时前
开发一个支持支付功能的微信小程序的注意事项，含泪送上
前端·后端·全栈
咕噜分发企业签名APP加固彭于晏1 小时前
腾讯元器的优点是什么
前端·后端
AAA修煤气灶刘哥2 小时前
Swagger 用着糟心？试试 Knife4j，后端开发狂喜
后端·面试
bobz9652 小时前
MCP on windows
后端
iOS开发上架哦3 小时前
移动端网页调试实战,键盘弹出与视口错位问题的定位与优化
后端
百度Geek说3 小时前
PaddleMIX推出扩散模型推理加速Fast-Diffusers：自研蒸馏加速方法FLUX-Lightning实现4步图像生成
后端
gopher_looklook3 小时前
Go并发实战：singleflight 源码解读与二次封装
数据结构·后端·go
用户833810251223 小时前
我为什么做PmMock：让接口设计不再头疼
前端·后端
热门推荐
01全球最强模型Grok4，国内已可免费使用！（附教程）02UV安装并设置国内源03Qwen3-Coder 快速上手教程 | Qwen Code + Claude Code04[已解决]VSCode右键菜单消失恢复052025最新国内服务器可用docker源仓库地址大全（2025年8月更新）06🚀Cursor CLI+GPT-5保姆级教程+编程能力测评！Cursor CLI零成本免费使用GPT-5！Claude Code的劲敌来了！从安装到实战演示07GPT-5 使用限制与国内升级全攻略（免费 / Plus / Pro）【2025 最新】08KGG转MP3工具|非KGM文件|解密音频09Cursor 终端“卡死/无响应”问题的解法10OpenAI重返开源！GPT-OSS本地部署完全指南