声明式Excel处理完全指南:JQuick-Excel的Mapping、Format与Transform精讲
- 2026-08-23 16:24:10
声明式Excel处理完全指南:JQuick-Excel的Mapping、Format与Transform精讲
FORMAT & MAPPING 使用指南（程序员版）
面向 Java 开发者的 JQuick-Excel 字段映射与单元格格式配置手册。阅读本文前建议先了解 README.md 中的基础 DSL 语法。
目录
设计理念 2.1 导出方向（EXPORT） 2.2 导入方向（IMPORT） 2.3 方向差异对比（重点） 2.4 字段过滤机制 2.5 完整代码示例 MAPPING：字段映射 3.1 基本语法 3.2 key 的含义（重点） 3.3 支持的格式类型 3.4 与主题样式的叠加关系 3.5 完整代码示例 FORMAT：单元格格式 进阶：MAPPING + FORMAT + TRANSFORM 组合 常见坑 & FAQ 快速参考表
1. 设计理念
MAPPING | |||
FORMAT | |||
TRANSFORM |
三者层级关系（导出时执行顺序）：
原始数据对象 → [MAPPING 决定哪些字段参与] → [TRANSFORM 改值] → [FORMAT 改显示] → 写入 Excel关键区别：
FORMAT是 Excel 层面的"数字格式掩码"（相当于在 Excel 里右键设置单元格格式），不会改动底层存储的数值；TRANSFORM是 Java 层面的值转换（如toUpperCase、dateFormat），会真正改变写入单元格的值。
2. MAPPING：字段映射
2.1 导出方向（EXPORT）
语法：
MAPPING = { ”源字段名” : ”Excel表头名” [, ...] }语义：
key = Java 数据对象 / Map中的字段名（源字段）value = 写入 Excel 第一行的表头文本
示例：
EXPORT WITHSHEET=”学生表”,HEADER=true,MAPPING={”id”:”主键”,”name”:”姓名”,”gender”:”性别”,”age”:”年龄”,”enrollmentDate”:”入学时间”,”className”:”班级”,”ignoreField”:”是否忽略”}
对应 Java 数据：
public class JStudentModel {private String id;private String name;private Integer gender;private Integer age;private Date enrollmentDate;private String className;private String ignoreField;// getters/setters...}
生成的 Excel：
public Void visitMappingOption(JQuickExcelParser.MappingOptionContext ctx) {Map mapping = new HashMap<>();for (JQuickExcelParser.FieldMappingContext fieldMappingContext : ctx.fieldMapping()) {JKeyValueModel fieldMappings = visitFieldMapping(fieldMappingContext);mapping.put(fieldMappings.getKey(), fieldMappings.getValue().toString());}config.setMapping(mapping);return null;}
2.2 导入方向（IMPORT）
语法：
MAPPING = { ”Excel列名” : ”目标字段名” [, ...] }语义（与导出相反）：
key = Excel 表头文本（源） value = 写入结果 Map的字段名（目标）
示例：
IMPORT WITHSHEET=”Sheet1”,HEADER=true,MAPPING={”学号”: ”no”,”姓名”: ”name”,”性别”: ”sex”,”年龄”: ”age”,”出生日期”: ”birthday”}
读取 Excel：
得到 Java 数据：
List rows = handler.importData(model);// 每行 Map 的 key 是：no / name / sex / age / birthday
源码追踪（JQuickExcelCommonImportVisitor.java:70-86）：
public Object visitMappingOption(JQuickExcelParser.MappingOptionContext ctx) {Map mappings = new HashMap<>();for (JQuickExcelParser.FieldMappingContext mapping : ctx.fieldMapping()) {if (null != mapping.STRING()) {String source = JStringUtils.trim(mapping.STRING(0).getText()); // Excel列名String target = mapping.STRING(1) != null? JStringUtils.trim(mapping.STRING(1).getText()) // 目标字段名: mapping.functionCall().getText(); // 或函数调用mappings.put(source, target);}}config.setMappings(mappings);return null;}
2.3 方向差异对比（重点）
⚠️这是最容易踩坑的地方——MAPPING 在导出和导入方向上 key/value 语义是相反的：
EXPORT | |||
IMPORT |
对称写法对照：
# 导出：Java 字段 enrollmentDate → Excel 表头”入学时间”EXPORT WITH MAPPING={ ”enrollmentDate”:”入学时间” }# 导入：Excel 列”入学时间” → Java 字段 enrollmentDateIMPORT WITH MAPPING={ ”入学时间”:”enrollmentDate” }
设计原因：MAPPING 始终遵循"源 → 目标"的语义。导出时源是 Java、目标是 Excel；导入时源是 Excel、目标是 Java。
2.4 字段过滤机制
MAPPING 还兼任"字段过滤"职责——未在 MAPPING 中声明的字段：
导出方向：仍会写入 Excel（表头用字段名本身，见 getOrDefault(header, header)）。要彻底排除某字段，需在数据转换阶段移除，或使用TRANSFORM处理。导入方向：不会出现在结果 Map中。即 MAPPING 同时是"白名单"。
💡 导入时若想跳过某列，直接不写进 MAPPING 即可；导出时若想跳过某字段，需在 Java 侧过滤掉。
2.5 完整代码示例
导出：
String rule = ”””EXPORT WITHSHEET=”学生表”,HEADER=true,MAPPING={”id”:”主键”,”name”:”姓名”,”gender”:”性别”,”age”:”年龄”,”enrollmentDate”:”入学时间”,”className”:”班级”}”””;List> data = JObjectConverter.convert(getStudentList());FileOutputStream fos = new FileOutputStream(”students.xlsx”);JQuickExcelCommonExportExecutor executor = new JQuickExcelCommonExportExecutor();JExcelExportModel config = (JExcelExportModel) executor.execute(rule);JExcelExportHandler handler = new JExcelExportHandler(config, data);handler.getWorkBook().write(fos);fos.close();
导入：
String rule = ”””IMPORT WITHSHEET=”Sheet1”,HEADER=true,MAPPING={”学号”: ”no”,”姓名”: ”name”,”性别”: ”sex”,”年龄”: ”age”,”出生日期”: ”birthday”}”””;JQuickExcelCommonImportExecutor executor = new JQuickExcelCommonImportExecutor();JExcelImportModel model = (JExcelImportModel) executor.execute(rule);InputStream is = new FileInputStream(”students.xlsx”);XSSFWorkbook workbook = new XSSFWorkbook(is);JExcelImportHandler handler = new JExcelImportHandler(workbook);List rows = handler.importData(model);
3. FORMAT：单元格格式
3.1 基本语法
FORMAT = { ”源字段名” : ”Excel格式字符串” [, ...] }仅用于 EXPORT，IMPORT 不支持 FORMAT（导入时如需格式化，请用 TRANSFORM 的 dateFormat 等函数）。
3.2 key 的含义（重点）
⚠️FORMAT 的 key 必须是源字段名（Java 字段名），不是 Excel 表头名！
这一点与 MAPPING 的 key 保持一致，但很多开发者会误以为要用 Excel 表头名。
正确：
MAPPING={ ”enrollmentDate”:”入学时间” },FORMAT={ ”enrollmentDate”:”yyyy-MM-dd” }# ✅ 用源字段名
错误：
MAPPING={ ”enrollmentDate”:”入学时间” },FORMAT={ ”入学时间”:”yyyy-MM-dd” }# ❌ 用表头名，不会生效
源码追踪（JExcelExportHandler.java:179-190）：
for (Map.Entry entry : rowData.entrySet()) { // entry.getKey() = 源字段名Cell cell = row.createCell(colNum++);// ... 写入值 ...String fmt = formats == null ? null : formats.get(entry.getKey()); // 用源字段名查格式CellStyle cellStyle = JCellStyleCache.getThemedDataWithFormat(workbook, theme, isOdd, fmt);cell.setCellStyle(cellStyle);}
3.3 支持的格式类型
FORMAT 的 value 会原样传给Workbook.createDataFormat().getFormat(format)，因此任何 Excel 原生支持的格式字符串都可用，DSL 解析器不做任何校验。
yyyy-MM-dd | 2025-01-23 | |
yyyy年m月d日 | 2025年1月23日 | |
hh:mm:ss | 14:30:00 | |
[h]:mm | 62:30 | |
0.00 | 3.14 | |
#,##0.00 | 1,234.56 | |
0.00% | 25.00% | |
0.00E+00 | 1.23E+03 | |
¥#,##0.00 | ¥1,234.56 | |
¥#,##0.00;[Red]-¥#,##0.00 | ||
0.0,"K" | 12341.2K | |
@ | ||
[>1000]"高";[>0]"中";"低" | ||
| 1.251 1/4 |
⚠️ 注意：格式串语法错误不会在导出时报错，POI 写入时不校验。问题要等 Excel 打开时才暴露（显示为默认格式或弹窗）。建议复杂格式先用 Excel 验证一遍。
3.4 与主题样式的叠加关系
FORMAT不会覆盖主题样式（边框、背景色、字体），而是在主题样式基础上叠加DataFormat。
public static CellStyle getThemedDataWithFormat(Workbook wb, JExcelTheme theme, boolean isOdd, String format) {CellStyle base = resolveBaseDataStyle(wb, theme, isOdd); // 先取主题基础样式if (format == null || format.isEmpty()) {return base; // 无格式直接返回基础样式}String key = (theme == null ? ”_DEF_” : ”_THEME_” + theme.getCode() + ”_”)+ (isOdd ? ”ODD” : ”EVEN”) + ”_FMT_” + format;return getStyleMap(wb).computeIfAbsent(key, k -> cloneStyleWithFormat(wb, base, format));}
缓存机制：同一个 workbook + theme + 奇偶 + format 组合只创建一个 CellStyle，避免触达 POI 的 64000 样式上限。即使百万行数据，只要格式串种类有限，样式对象数量就是常数级。
3.5 完整代码示例
String rule = ”””EXPORT WITHSHEET=”学生表”,HEADER=true,MAPPING={”id”:”主键”,”name”:”姓名”,”age”:”年龄”,”enrollmentDate”:”入学时间”,”salary”:”薪资”},FORMAT={”enrollmentDate”:”yyyy-MM-dd”,”age”:”0”,”salary”:”¥#,##0.00;[Red]-¥#,##0.00”}”””;List> data = JObjectConverter.convert(getStudentList());FileOutputStream fos = new FileOutputStream(”formatted.xlsx”);JQuickExcelCommonExportExecutor executor = new JQuickExcelCommonExportExecutor();JExcelExportModel config = (JExcelExportModel) executor.execute(rule);// 可选：配合主题使用，FORMAT 会叠加在主题样式之上config.setTheme(”royalGold”);JExcelExportHandler handler = new JExcelExportHandler(config, data);handler.getWorkBook().write(fos);fos.close();
生成效果：
4. 进阶：MAPPING + FORMAT + TRANSFORM 组合
三者各司其职，组合使用时执行顺序为MAPPING（选字段）→ TRANSFORM（改值）→ FORMAT（改显示）。
EXPORT WITHSHEET=”学生表”,HEADER=true,MAPPING={”id”:”主键”,”name”:”姓名”,”gender”:”性别”,”enrollmentDate”:”入学时间”,”salary”:”薪资”},FORMAT={”enrollmentDate”:”yyyy-MM-dd”,# 显示层：日期格式”salary”:”¥#,##0.00”# 显示层：货币格式},TRANSFORM={”name”: toUpper(${name}),# 值层：姓名转大写”enrollmentDate”: dateFormat(${enrollmentDate},'yyyy-MM-dd'),# 值层：Date→String”gender”: trans(${dict},${gender})# 值层：1/0 → 男/女}
关键区别：
TRANSFORM中的 dateFormat把Date对象转成String写入单元格 → 单元格存的是字符串FORMAT的 yyyy-MM-dd让单元格按日期格式显示 → 单元格存的是 Date 数值，只是显示成日期
推荐做法：
若需要在 Excel 中保留"真正的日期类型"（可排序、可参与公式），不要用 TRANSFORM 的 dateFormat，只用 FORMAT 若需要导入时反向解析，TRANSFORM 的 dateFormat 更可控
Java 侧上下文传递（TRANSFORM 用到 ${dict} 时需要注入）：
HashMap dict = new HashMap<>();dict.put(”1”, ”男”);dict.put(”0”, ”女”);JContext context = new JContext();context.put(”dict”, dict);JExcelExportHandler handler = new JExcelExportHandler(config, context, JQuickRow.toRows(data));
5. 常见坑 & FAQ
Q1：FORMAT 配置了但不生效？
排查清单：
❓ key 是否用了 Excel 表头名？→ 必须用源字段名（与 MAPPING 的 key 一致） ❓ 是否在 IMPORT 规则里用了 FORMAT？→ FORMAT 仅支持 EXPORT ❓ 格式串是否有语法错误？→ POI 不校验，用 Excel 先验证 ❓ 字段是否在 MAPPING 中声明？→ 导出时未声明的字段仍会输出，但 FORMAT 同样以源字段名为 key 生效
Q2：MAPPING 在导出和导入方向写反了怎么办？
记住口诀："源 → 目标"。
导出：源是 Java，目标是 Excel → "javaField":"excelHeader"导入：源是 Excel，目标是 Java → "excelHeader":"javaField"
Q3：导出时如何排除某个字段？
MAPPING 不能直接排除字段（未声明的字段会用字段名本身作为表头输出）。两种方案：
数据层过滤：在 JObjectConverter.convert前移除字段，或用@JsonIgnore等注解用 Map 精确控制：把 List<POJO>转成List<Map>时只保留需要的 key
Q4：FORMAT 会触达 POI 的 64000 样式上限吗？
不会。JCellStyleCache 对 workbook + theme + 奇偶 + format 组合做了缓存（JCellStyleCache.java:117-122），同种组合只创建一个 CellStyle。即便百万行，只要格式串种类有限（通常 < 20 种），样式对象就是常数级。
Q5：FORMAT 和 STYLE 有什么区别？
FORMAT：只设置 DataFormat（数字/日期格式掩码），保留主题的边框/背景/字体STYLE：完整的单元格样式控制（可覆盖边框、背景、字体、对齐等），优先级更高
需要完整自定义样式时用 STYLE，只调数字/日期格式时用 FORMAT 更轻量。
Q6：导入时怎么格式化日期？
IMPORT 不支持 FORMAT。用 TRANSFORM：
IMPORT WITHMAPPING={ ”出生日期”:”birthday” },TRANSFORM={”birthday”: dateFormat(${birthday},'yyyy-MM-dd')}
6. 快速参考表
MAPPING
EXPORT WITH MAPPING={ "id":"主键" } | |||
IMPORT WITH MAPPING={ "学号":"no" } |
FORMAT
EXPORT WITH FORMAT={ "enrollmentDate":"yyyy-MM-dd" } | |||
常用格式串速查
yyyy-MM-dd | |
yyyy年m月d日 | |
hh:mm:ss | |
0.00 | |
#,##0.00 | |
0.00% | |
¥#,##0.00 | |
¥#,##0.00;[Red]-¥#,##0.00 | |
@ |
三者关系速查
MAPPING | ||||
FORMAT | ||||
TRANSFORM |
相关文档
README.md - 项目总览与完整 DSL 语法 README_EN.md - English documentation benchmark.md - 性能基准测试报告 template.md - 主题模板预览
本文来自网友投稿或网络内容，如有侵犯您的权益请联系我们删除，联系邮箱：wyl860211@qq.com 。
