夜雨聆风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 中通常这样写：
<![CDATA[EXPORT WITHSHEET=”学生表”,HEADER=true,MAPPING={”id”:”主键”,”name”:”姓名”,”gender”:”性别”,”age”:”年龄”},STYLE={ROW 1: {fontName: Arial,fontHeightInPoints: 12,italic: true,color: yellow,bold: true}}]]>
说明：
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 字体类属性
fontName | Arial | ||
fontHeightInPoints | 12 | ||
fontHeight | 240 | ||
bold | true | ||
italic | true | ||
underLine | single | ||
color | red | ||
strikeout | true |
示例：
STYLE={ROW 1: {fontName: Arial,fontHeightInPoints: 12,bold: true,italic: false,color: white,underLine: single}}
underLine不是布尔值，而是字符串类型的下划线样式名称。
5.2 对齐类属性
alignment | leftright / center / general / fill / justify / distributed / center-section | ||
verticalAlignment | topbottom / center / justify / distributed | ||
wrapText | truefalse | ||
rotation | 090 等 | ||
indention | 12 等 | ||
shrinkToFit | truefalse |
示例：
STYLE={COL B: {alignment: center,verticalAlignment: center,wrapText: true}}
5.3 边框类属性
borderLeft | thin | ||
borderRight | thin | ||
borderTop | medium | ||
borderBottom | double | ||
leftBorderColor | red | ||
rightBorderColor | blue | ||
topBorderColor | green | ||
bottomBorderColor | black |
支持的边框样式值：
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 填充类属性
fillPattern | solid_foreground | ||
fillForegroundColor | blue | ||
fillBackgroundColor | yellow |
支持的 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 其他单元格属性
hidden | true | ||
locked | true | ||
quotePrefixed | true | ||
dataFormat | 14 | ||
dataFormatString | yyyy-MM-dd |
说明：
hidden/ locked已在 helper 中真正应用dataFormat/ dataFormatString在模型中存在，但当前JStyleHelper.applyCellStyle(...)没有实际设置逻辑如果要处理显示格式，当前更推荐优先使用独立的 FORMAT配置项，而不是依赖 STYLE 中的dataFormat
5.6 行专属属性
这些属性主要用于 ROW 样式：
height | 800 | ||
heightInPoints | 30 | ||
zeroHeight | true | ||
rowStyle | {...} |
示例：
STYLE={ROW 1: {heightInPoints: 30,bold: true,alignment: center}}
日常 XML 配置里更常用的是
heightInPoints、bold、color这类直观属性。rowStyle更偏底层编程式能力。
6. 最小可运行示例
<![CDATA[EXPORT WITHSHEET=”学生表”,HEADER=true,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}}]]>
效果：
第 1 行表头加粗 字体白色 背景蓝色 水平、垂直居中
7. 常见配置示例
7.1 表头高亮
<![CDATA[EXPORT WITHSHEET=”学生表”,HEADER=true,STYLE={ROW 1: {bold: true,color: white,fillPattern: solid_foreground,fillForegroundColor: navy,alignment: center,verticalAlignment: center,heightInPoints: 28}}]]>
用途：
做标题区、表头区高亮
7.2 数据列统一样式
<![CDATA[EXPORT WITHSHEET=”学生表”,HEADER=true,STYLE={COL D: {alignment: right,borderBottom: thin,borderLeft: thin,borderRight: thin},COL E: {alignment: center,wrapText: true}}]]>
用途：
数值列右对齐 日期列或说明列统一样式
7.3 单元格重点标记
<![CDATA[EXPORT WITHSHEET=”学生表”,HEADER=true,STYLE={A1: {bold: true,fillPattern: solid_foreground,fillForegroundColor: red,color: white},D5: {bold: true,borderTop: double,borderBottom: double,alignment: center}}]]>
用途：
特殊标题格 汇总结果格 警示信息格
7.4 行高与隐藏行
<![CDATA[EXPORT WITHSHEET=”学生表”,HEADER=true,STYLE={ROW 1: {heightInPoints: 32,bold: true},ROW 10: {zeroHeight: true}}]]>
用途：
拉高表头 隐藏辅助行
7.5 组合样式
<![CDATA[EXPORT WITHSHEET=”学生表”,HEADER=true,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}}]]>
用途：
表头、数据列、汇总格同时做差异化视觉设计
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.5 dataFormat / dataFormatString 当前不建议通过 STYLE 使用
虽然模型里有这两个字段，但 helper 当前没有真正落地这两个属性。
建议：
显示格式优先使用 FORMAT配置项STYLE主要用来做字体、对齐、边框、填充、行高这类视觉控制
11. 常见问题与避坑指南
11.1 为什么我设置了背景色但没显示？
大概率是少了：
fillPattern: solid_foreground推荐这样一起写：
fillPattern: solid_foreground,fillForegroundColor: blue
11.2 为什么 RANGE 样式写了没效果？
因为当前版本的 applyStyle 没有处理 rangeStyles。
解决方式：
拆成多行 拆成多列 或多个单元格单独写
11.3 为什么用了 STYLE 后流式导出没生效？
因为框架检测到样式配置需要随机访问已写行，会自动禁用 SXSSF，回退到 XSSF。
11.4 ROW 1 是第 0 行还是第 1 行？
按 Excel 习惯，ROW 1 就是第一行，不是 Java 下标 0。
11.5 列目标应该写数字还是列字母？
当前实现两种都能兼容一部分：
数字列索引 类似 D这种列标识
但从可读性和 DSL 风格上，推荐统一写COL D、COL B..E这种 Excel 风格表达。
11.6 字体颜色、边框颜色、填充颜色支持什么值？
当前是通过颜色枚举映射的，推荐使用常见英文颜色名，例如：
redblueyellowgreenwhiteblacknavy
如果某个颜色名无效，优先换成常见基础色测试。
11.7 行样式为什么没有作用到空白单元格？
因为行样式只处理该行已经存在的单元格，不会自动把这一整行所有可能列都建出来。
如果你需要确保某个目标单元格一定被设置，建议直接用单元格样式。
12. 推荐实践
站在程序员角度，推荐这样使用 STYLE：
12.1 主题 + 局部样式覆盖，是最实用组合
建议：
先用主题统一整体视觉 再用 STYLE微调表头、汇总格、重点列
这样能兼顾：
一致性 可读性 开发效率
12.2 表头优先用行样式
表头通常天然就是整行，最适合：
ROW 1: { ... }比逐格写更简洁。
12.3 重点值优先用单元格样式
例如：
合计 预警 备注 特殊标识位
推荐直接精确到格：
D5: { ... }12.4 大数据导出尽量少用复杂 STYLE
因为 STYLE 会导致随机访问、禁用流式、增加样式处理成本。
如果你的目标是极致吞吐，建议：
少量关键样式 不做复杂回写 不做大面积逐格装饰
12.5 先保证数据正确，再做视觉精修
真实项目里最容易过度设计 Excel 样式。
建议顺序：
先保证字段、值、格式、公式都正确 再加表头和重点区域样式 最后再考虑边框、填充、字体等美化细节
这样最稳。