JQuick-Excel 导出 STYLE 配置项使用手册本手册专门介绍 jquick-excel 导出场景中的STYLE配置项包括语法结构、目标范围、可用样式属性、执行顺序、与主题/公式/流式导出的关系以及实际使用中的坑点。文档示例统一采用 XML / DSL 声明式写法方便直接落到jquick-excel.xml。目录STYLE 是什么基础语法四类目标范围3.1 行样式3.2 列样式3.3 单元格样式3.4 区域样式STYLE 的执行时机可用样式属性5.1 字体类属性5.2 对齐类属性5.3 边框类属性5.4 填充类属性5.5 其他单元格属性5.6 行专属属性最小可运行示例常见配置示例7.1 表头高亮7.2 数据列统一样式7.3 单元格重点标记7.4 行高与隐藏行7.5 组合样式STYLE 与 THEME / FORMULAS / TRANSFORM 的关系STYLE 与 SXSSF 流式导出的限制当前实现特性与注意事项常见问题与避坑指南推荐实践1. STYLE 是什么STYLE用于在Excel 导出阶段对已经写入到工作表中的行、列、单元格应用样式。它解决的问题不是“字段值怎么转换”而是“最终 Excel 长什么样”。典型场景表头加粗、变色、居中某一列统一设置边框、对齐、背景色对特定单元格做高亮提示调整行高、隐藏辅助行给汇总区、备注区设置不同视觉风格一句话理解TRANSFORM 负责“值” STYLE 负责“样子”2. 基础语法STYLE的基本结构如下STYLE { 目标: { 样式属性: 值, 样式属性: 值 }, 目标: { 样式属性: 值 } }在完整导出 DSL 中通常这样写excelnameexportExcelreturnClassvoid![CDATA[ EXPORT WITH SHEET学生表, HEADERtrue, MAPPING{ id:主键, name:姓名, gender:性别, age:年龄 }, STYLE{ ROW 1: { fontName: Arial, fontHeightInPoints: 12, italic: true, color: yellow, bold: true } } ]]/excel说明部分说明STYLE固定关键字表示样式配置块目标可以是行、列、单元格、区域样式属性具体样式项如bold、alignment、borderBottom值字符串、数字、布尔值等多目标使用英文逗号分隔3. 四类目标范围从解析器和导出实现看STYLE支持以下四类目标行样式ROW列样式COL单元格样式A1区域样式A1:C5不过要特别注意当前导出执行逻辑只真正应用了 行 / 列 / 单元格 三类样式RANGE虽然能被解析并存入配置但在applyStyle中没有真正落地执行。3.1 行样式语法STYLE{ ROW 1: { bold: true, color: red } }也支持行范围STYLE{ ROW 2..5: { heightInPoints: 30, alignment: center } }含义对第 1 行所有已存在单元格应用样式对第 2~5 行所有已存在单元格应用相同样式适合场景表头行汇总行备注行整行强调展示3.2 列样式语法STYLE{ COL D: { alignment: right, borderBottom: thin } }也支持列范围STYLE{ COL B..E: { wrapText: true, verticalAlignment: center } }含义对指定列中所有已遍历到的行应用样式如果某行该列单元格不存在会自动创建该单元格再设置样式适合场景年龄列、金额列统一右对齐日期列统一居中某一组指标列统一边框和背景色3.3 单元格样式语法STYLE{ A1: { bold: true, color: white, fillForegroundColor: blue, fillPattern: solid_foreground } }含义只对单个目标单元格应用样式若单元格不存在会自动创建适合场景特定标题格汇总结果格风险提示格手工标识位3.4 区域样式语法STYLE{ A1:C3: { borderBottom: thin, borderTop: thin, alignment: center } }源码现状说明解析器支持rangeStyle访问器会把区域样式存入config.getRangeStyles()但当前JExcelExportHandler.applyStyle(...)只处理了rowStylescolStylescellStyles没有处理rangeStyles所以当前版本里RANGE 样式语法可写但不会真正生效如果你需要区域样式当前更稳妥的做法是拆成多行样式或拆成多列样式或逐个单元格样式4. STYLE 的执行时机从导出处理流程看执行顺序如下写表头 → 写数据 → 应用公式 → 应用样式 → 应用合并 → 应用图表这意味着先把数据和表头写到 sheet再应用FORMULAS再执行STYLE因此STYLE是对“已经存在的工作表内容”做修饰。这也带来两个重要结论样式可以覆盖公式单元格样式在大数据场景下常常意味着“回头修改已写过的行”后者与流式写出有冲突后面会专门讲。5. 可用样式属性从JCellStyle、JRowStyle、JFontStyle、JStyleHelper和字体构建逻辑来看当前 STYLE 支持的属性主要分为以下几类。5.1 字体类属性属性类型示例说明fontNamestringArial字体名称fontHeightInPointsnumber12字体大小ptfontHeightnumber240字体高度POI 原始单位boldbooleantrue是否加粗italicbooleantrue是否斜体underLinestringsingle下划线类型colorstringred字体颜色strikeoutbooleantrue删除线示例STYLE{ ROW 1: { fontName: Arial, fontHeightInPoints: 12, bold: true, italic: false, color: white, underLine: single } }underLine不是布尔值而是字符串类型的下划线样式名称。5.2 对齐类属性属性类型可选值说明alignmentstringleft/right/center/general/fill/justify/distributed/center-section水平对齐verticalAlignmentstringtop/bottom/center/justify/distributed垂直对齐wrapTextbooleantrue/false自动换行rotationnumber0、90等文本旋转indentionnumber1、2等缩进shrinkToFitbooleantrue/false缩小字体填充示例STYLE{ COL B: { alignment: center, verticalAlignment: center, wrapText: true } }5.3 边框类属性属性类型示例说明borderLeftstringthin左边框borderRightstringthin右边框borderTopstringmedium上边框borderBottomstringdouble下边框leftBorderColorstringred左边框颜色rightBorderColorstringblue右边框颜色topBorderColorstringgreen上边框颜色bottomBorderColorstringblack下边框颜色支持的边框样式值nonethinmediumdasheddottedthickdoublehairmedium_dasheddash_dotmedium_dash_dotdash_dot_dotmedium_dash_dot_dotslanted_dash_dot示例STYLE{ A1: { borderLeft: thin, borderRight: thin, borderTop: medium, borderBottom: medium, leftBorderColor: red, rightBorderColor: red } }5.4 填充类属性属性类型示例说明fillPatternstringsolid_foreground填充图案fillForegroundColorstringblue前景色fillBackgroundColorstringyellow背景色支持的fillPattern常见值no_fillsolid_foregroundfine_dotsalt_barssparse_dotsthick_horz_bandsthick_vert_bandsthick_backward_diagthick_forward_diagbig_spotsbricksthin_horz_bandsthin_vert_bandsthin_backward_diagthin_forward_diagsquaresdiamondsless_dotsleast_dots示例STYLE{ A1: { fillPattern: solid_foreground, fillForegroundColor: blue, color: white, bold: true } }仅设置颜色通常不够建议同时设置fillPattern: solid_foreground否则填充色可能看不出来。5.5 其他单元格属性属性类型示例说明hiddenbooleantrue隐藏公式等内容lockedbooleantrue锁定单元格quotePrefixedbooleantrue前置单引号语义dataFormatnumber14数据格式索引dataFormatStringstringyyyy-MM-dd数据格式字符串当前 helper 未实际应用说明hidden/locked已在 helper 中真正应用dataFormat/dataFormatString在模型中存在但当前JStyleHelper.applyCellStyle(...)没有实际设置逻辑如果要处理显示格式当前更推荐优先使用独立的FORMAT配置项而不是依赖 STYLE 中的dataFormat5.6 行专属属性这些属性主要用于ROW样式属性类型示例说明heightnumber800行高原始单位heightInPointsnumber30行高ptzeroHeightbooleantrue是否隐藏整行rowStyleobject{...}行级内部样式对象更偏底层用法示例STYLE{ ROW 1: { heightInPoints: 30, bold: true, alignment: center } }日常 XML 配置里更常用的是heightInPoints、bold、color这类直观属性。rowStyle更偏底层编程式能力。6. 最小可运行示例excelnameexportWithStylereturnClassvoid![CDATA[ EXPORT WITH SHEET学生表, HEADERtrue, MAPPING{ id:主键, name:姓名, gender:性别, age:年龄 }, STYLE{ ROW 1: { fontName: Arial, fontHeightInPoints: 12, bold: true, color: white, fillPattern: solid_foreground, fillForegroundColor: blue, alignment: center, verticalAlignment: center } } ]]/excel效果第 1 行表头加粗字体白色背景蓝色水平、垂直居中7. 常见配置示例7.1 表头高亮excelnameexportHeaderStylereturnClassvoid![CDATA[ EXPORT WITH SHEET学生表, HEADERtrue, STYLE{ ROW 1: { bold: true, color: white, fillPattern: solid_foreground, fillForegroundColor: navy, alignment: center, verticalAlignment: center, heightInPoints: 28 } } ]]/excel用途做标题区、表头区高亮7.2 数据列统一样式excelnameexportColumnStylereturnClassvoid![CDATA[ EXPORT WITH SHEET学生表, HEADERtrue, STYLE{ COL D: { alignment: right, borderBottom: thin, borderLeft: thin, borderRight: thin }, COL E: { alignment: center, wrapText: true } } ]]/excel用途数值列右对齐日期列或说明列统一样式7.3 单元格重点标记excelnameexportCellStylereturnClassvoid![CDATA[ EXPORT WITH SHEET学生表, HEADERtrue, STYLE{ A1: { bold: true, fillPattern: solid_foreground, fillForegroundColor: red, color: white }, D5: { bold: true, borderTop: double, borderBottom: double, alignment: center } } ]]/excel用途特殊标题格汇总结果格警示信息格7.4 行高与隐藏行excelnameexportRowHeightStylereturnClassvoid![CDATA[ EXPORT WITH SHEET学生表, HEADERtrue, STYLE{ ROW 1: { heightInPoints: 32, bold: true }, ROW 10: { zeroHeight: true } } ]]/excel用途拉高表头隐藏辅助行7.5 组合样式excelnameexportComplexStylereturnClassvoid![CDATA[ EXPORT WITH SHEET学生表, HEADERtrue, STYLE{ ROW 1: { bold: true, color: white, fillPattern: solid_foreground, fillForegroundColor: blue, alignment: center, verticalAlignment: center, borderBottom: medium, bottomBorderColor: white, heightInPoints: 30 }, COL D: { alignment: right, borderRight: thin }, D5: { bold: true, fillPattern: solid_foreground, fillForegroundColor: yellow, color: red, borderTop: double, borderBottom: double } } ]]/excel用途表头、数据列、汇总格同时做差异化视觉设计8. STYLE 与 THEME / FORMULAS / TRANSFORM 的关系8.1 与 THEME 的关系jquick-excel 已经支持主题模板导出时默认会先给表头和数据区套主题样式。STYLE的定位更像“主题之上的精细化覆盖”。可以这样理解THEME 负责整体视觉基调 STYLE 负责局部精修适合做法先选一个主题作为基础皮肤再用STYLE对表头、汇总区、关键单元格做定制8.2 与 FORMULAS 的关系执行顺序上FORMULAS → STYLE因此公式单元格可以再被样式修饰常见做法是给汇总公式结果格设置加粗、背景色、边框8.3 与 TRANSFORM 的关系两者关注点完全不同配置项作用阶段作用内容TRANSFORM写值时数据转换STYLE写值后视觉样式一般来说TRANSFORM解决数据值长什么样STYLE解决用户看到的表格长什么样9. STYLE 与 SXSSF 流式导出的限制这是 STYLE 在大数据导出里最重要的限制之一。因为STYLE的执行发生在数据写完之后它通常需要回头取某一行回头取某一列的单元格回头修改已写入的 cellStyle而 SXSSF 流式写入的特点是只保留有限窗口内的行在内存里更早的行可能已经刷盘刷盘后不允许再安全回写因此当前框架已经做了保护只要配置中出现ROW / COLUMN / CELL / RANGE样式needsRandomRowAccess(config)就会返回true自动禁用 SXSSF降级回XSSFWorkbook也就是说只要用了 STYLE通常就不再走纯流式导出这很合理因为样式本质上就是“回头修饰”。10. 当前实现特性与注意事项这一节很重要属于“站在程序员角度必须知道的实现细节”。10.1 行样式只会作用于“该行已存在的单元格”行样式策略内部是遍历for (int i 0; i row.getLastCellNum(); i)因此只会处理该行当前已有的单元格不会主动补齐不存在的后续单元格10.2 列样式会自动创建缺失单元格列样式策略内部如果某行该列单元格不存在会自动createCell(colNum)。因此列样式通常比行样式更“主动”。10.3 单元格样式会自动创建行和单元格如果目标格对应的行或单元格不存在单元格样式策略会自动创建。所以单元格样式是最稳妥的精确控制方式。10.4 RANGE 样式当前不会真正生效再次强调一遍解析支持配置模型支持访问器支持导出应用逻辑未接入如果你写STYLE{ A1:C3: { borderBottom: thin } }当前版本里大概率不会生效。10.5dataFormat/dataFormatString当前不建议通过 STYLE 使用虽然模型里有这两个字段但 helper 当前没有真正落地这两个属性。建议显示格式优先使用FORMAT配置项STYLE主要用来做字体、对齐、边框、填充、行高这类视觉控制11. 常见问题与避坑指南11.1 为什么我设置了背景色但没显示大概率是少了fillPattern: solid_foreground推荐这样一起写fillPattern: solid_foreground, fillForegroundColor: blue11.2 为什么 RANGE 样式写了没效果因为当前版本的applyStyle没有处理rangeStyles。解决方式拆成多行拆成多列或多个单元格单独写11.3 为什么用了 STYLE 后流式导出没生效因为框架检测到样式配置需要随机访问已写行会自动禁用 SXSSF回退到 XSSF。11.4ROW 1是第 0 行还是第 1 行按 Excel 习惯ROW 1就是第一行不是 Java 下标 0。11.5 列目标应该写数字还是列字母当前实现两种都能兼容一部分数字列索引类似D这种列标识但从可读性和 DSL 风格上推荐统一写COL D、COL B..E这种 Excel 风格表达。11.6 字体颜色、边框颜色、填充颜色支持什么值当前是通过颜色枚举映射的推荐使用常见英文颜色名例如redblueyellowgreenwhiteblacknavy如果某个颜色名无效优先换成常见基础色测试。11.7 行样式为什么没有作用到空白单元格因为行样式只处理该行已经存在的单元格不会自动把这一整行所有可能列都建出来。如果你需要确保某个目标单元格一定被设置建议直接用单元格样式。12. 推荐实践站在程序员角度推荐这样使用STYLE12.1 主题 局部样式覆盖是最实用组合建议先用主题统一整体视觉再用STYLE微调表头、汇总格、重点列这样能兼顾一致性可读性开发效率12.2 表头优先用行样式表头通常天然就是整行最适合ROW 1: { ... }比逐格写更简洁。12.3 重点值优先用单元格样式例如合计预警备注特殊标识位推荐直接精确到格D5: { ... }12.4 大数据导出尽量少用复杂 STYLE因为 STYLE 会导致随机访问、禁用流式、增加样式处理成本。如果你的目标是极致吞吐建议少量关键样式不做复杂回写不做大面积逐格装饰12.5 先保证数据正确再做视觉精修真实项目里最容易过度设计 Excel 样式。建议顺序先保证字段、值、格式、公式都正确再加表头和重点区域样式最后再考虑边框、填充、字体等美化细节这样最稳。相关源码位置纯文本说明样式解析访问器src/main/java/com/github/paohaijiao/visitor/JQuickExcelExportStyleVisitor.java样式应用入口src/main/java/com/github/paohaijiao/handler/JExcelExportHandler.java样式上下文src/main/java/com/github/paohaijiao/jstyle/context/JStyleContext.java行样式策略src/main/java/com/github/paohaijiao/jstyle/strategry/impl/JRowStyleStrategy.java列样式策略src/main/java/com/github/paohaijiao/jstyle/strategry/impl/JColumnStyleStrategy.java单元格样式策略src/main/java/com/github/paohaijiao/jstyle/strategry/impl/JCellStyleStrategy.java单元格样式模型src/main/java/com/github/paohaijiao/jstyle/model/JCellStyle.java测试示例src/test/java/com/github/paohaijiao/export/style/