声明式Excel样式编排：JQuick-Export STYLE 设计解析与30+配置属性详解JQuick-Excel

JQuick-Excel 导出 STYLE 配置项使用手册

本手册专门介绍 jquick-excel 导出场景中的 STYLE 配置项，包括语法结构、目标范围、可用样式属性、执行顺序、与主题/公式/流式导出的关系，以及实际使用中的坑点。

文档示例统一采用 XML / DSL 声明式写法，方便直接落到 jquick-excel.xml。

1. STYLE 是什么
1. 基础语法
1. 四类目标范围
- 3.1 行样式
- 3.2 列样式
- 3.3 单元格样式
- 3.4 区域样式
1. STYLE 的执行时机
1. 可用样式属性
- 5.1 字体类属性
- 5.2 对齐类属性
- 5.3 边框类属性
- 5.4 填充类属性
- 5.5 其他单元格属性
- 5.6 行专属属性
1. 最小可运行示例
1. 常见配置示例
- 7.1 表头高亮
- 7.2 数据列统一样式
- 7.3 单元格重点标记
- 7.4 行高与隐藏行
- 7.5 组合样式
1. STYLE 与 THEME / FORMULAS / TRANSFORM 的关系
1. STYLE 与 SXSSF 流式导出的限制
1. 当前实现特性与注意事项
1. 常见问题与避坑指南
1. 推荐实践

1. STYLE 是什么

STYLE 用于在 Excel 导出阶段 对已经写入到工作表中的行、列、单元格应用样式。

它解决的问题不是“字段值怎么转换”，而是“最终 Excel 长什么样”。

典型场景：

表头加粗、变色、居中
某一列统一设置边框、对齐、背景色
对特定单元格做高亮提示
调整行高、隐藏辅助行
给汇总区、备注区设置不同视觉风格

一句话理解：

TRANSFORM 负责“值”
STYLE 负责“样子”

2. 基础语法

STYLE 的基本结构如下：

STYLE = {
    目标: {
        样式属性: 值,
        样式属性: 值
    },
    目标: {
        样式属性: 值
    }
}

在完整导出 DSL 中通常这样写：

<excel name="exportExcel" returnClass="void">
    <![CDATA[
    EXPORT WITH
        SHEET="学生表",
        HEADER=true,
        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(...) 只处理了：
- rowStyles
- colStyles
- cellStyles
没有处理 rangeStyles

所以当前版本里：

RANGE 样式语法可写，但不会真正生效

如果你需要区域样式，当前更稳妥的做法是：

拆成多行样式
或拆成多列样式
或逐个单元格样式

4. STYLE 的执行时机

从导出处理流程看，执行顺序如下：

写表头 → 写数据 → 应用公式 → 应用样式 → 应用合并 → 应用图表

这意味着：

先把数据和表头写到 sheet
再应用 FORMULAS
再执行 STYLE

因此 STYLE 是对“已经存在的工作表内容”做修饰。

这也带来两个重要结论：

样式可以覆盖公式单元格
样式在大数据场景下常常意味着“回头修改已写过的行”

后者与流式写出有冲突，后面会专门讲。

5. 可用样式属性

从 JCellStyle、JRowStyle、JFontStyle、JStyleHelper 和字体构建逻辑来看，当前 STYLE 支持的属性主要分为以下几类。

5.1 字体类属性

属性	类型	示例	说明
`fontName`	string	`Arial`	字体名称
`fontHeightInPoints`	number	`12`	字体大小（pt）
`fontHeight`	number	`240`	字体高度（POI 原始单位）
`bold`	boolean	`true`	是否加粗
`italic`	boolean	`true`	是否斜体
`underLine`	string	`single`	下划线类型
`color`	string	`red`	字体颜色
`strikeout`	boolean	`true`	删除线

示例：

STYLE={
    ROW 1: {
        fontName: Arial,
        fontHeightInPoints: 12,
        bold: true,
        italic: false,
        color: white,
        underLine: single
    }
}

underLine 不是布尔值，而是字符串类型的下划线样式名称。

5.2 对齐类属性

属性	类型	可选值	说明
`alignment`	string	`left` / `right` / `center` / `general` / `fill` / `justify` / `distributed` / `center-section`	水平对齐
`verticalAlignment`	string	`top` / `bottom` / `center` / `justify` / `distributed`	垂直对齐
`wrapText`	boolean	`true` / `false`	自动换行
`rotation`	number	`0`、`90` 等	文本旋转
`indention`	number	`1`、`2` 等	缩进
`shrinkToFit`	boolean	`true` / `false`	缩小字体填充

示例：

STYLE={
    COL B: {
        alignment: center,
        verticalAlignment: center,
        wrapText: true
    }
}

5.3 边框类属性

属性	类型	示例	说明
`borderLeft`	string	`thin`	左边框
`borderRight`	string	`thin`	右边框
`borderTop`	string	`medium`	上边框
`borderBottom`	string	`double`	下边框
`leftBorderColor`	string	`red`	左边框颜色
`rightBorderColor`	string	`blue`	右边框颜色
`topBorderColor`	string	`green`	上边框颜色
`bottomBorderColor`	string	`black`	下边框颜色

支持的边框样式值：

none
thin
medium
dashed
dotted
thick
double
hair
medium_dashed
dash_dot
medium_dash_dot
dash_dot_dot
medium_dash_dot_dot
slanted_dash_dot

示例：

STYLE={
    A1: {
        borderLeft: thin,
        borderRight: thin,
        borderTop: medium,
        borderBottom: medium,
        leftBorderColor: red,
        rightBorderColor: red
    }
}

5.4 填充类属性

属性	类型	示例	说明
`fillPattern`	string	`solid_foreground`	填充图案
`fillForegroundColor`	string	`blue`	前景色
`fillBackgroundColor`	string	`yellow`	背景色

支持的 fillPattern 常见值：

no_fill
solid_foreground
fine_dots
alt_bars
sparse_dots
thick_horz_bands
thick_vert_bands
thick_backward_diag
thick_forward_diag
big_spots
bricks
thin_horz_bands
thin_vert_bands
thin_backward_diag
thin_forward_diag
squares
diamonds
less_dots
least_dots

示例：

STYLE={
    A1: {
        fillPattern: solid_foreground,
        fillForegroundColor: blue,
        color: white,
        bold: true
    }
}

仅设置颜色通常不够，建议同时设置 fillPattern: solid_foreground，否则填充色可能看不出来。

5.5 其他单元格属性

属性	类型	示例	说明
`hidden`	boolean	`true`	隐藏公式等内容
`locked`	boolean	`true`	锁定单元格
`quotePrefixed`	boolean	`true`	前置单引号语义
`dataFormat`	number	`14`	数据格式索引
`dataFormatString`	string	`yyyy-MM-dd`	数据格式字符串（当前 helper 未实际应用）

说明：

hidden / locked 已在 helper 中真正应用
dataFormat / dataFormatString 在模型中存在，但当前 JStyleHelper.applyCellStyle(...) 没有实际设置逻辑
如果要处理显示格式，当前更推荐优先使用独立的 FORMAT 配置项，而不是依赖 STYLE 中的 dataFormat

5.6 行专属属性

这些属性主要用于 ROW 样式：

属性	类型	示例	说明
`height`	number	`800`	行高（原始单位）
`heightInPoints`	number	`30`	行高（pt）
`zeroHeight`	boolean	`true`	是否隐藏整行
`rowStyle`	object	`{...}`	行级内部样式对象（更偏底层用法）

示例：

STYLE={
    ROW 1: {
        heightInPoints: 30,
        bold: true,
        alignment: center
    }
}

日常 XML 配置里更常用的是 heightInPoints、bold、color 这类直观属性。rowStyle 更偏底层编程式能力。

6. 最小可运行示例

<excel name="exportWithStyle" returnClass="void">
    <![CDATA[
    EXPORT WITH
        SHEET="学生表",
        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
            }
        }
    ]]>
</excel>

效果：

第 1 行表头加粗
字体白色
背景蓝色
水平、垂直居中

7. 常见配置示例

7.1 表头高亮

<excel name="exportHeaderStyle" returnClass="void">
    <![CDATA[
    EXPORT WITH
        SHEET="学生表",
        HEADER=true,
        STYLE={
            ROW 1: {
                bold: true,
                color: white,
                fillPattern: solid_foreground,
                fillForegroundColor: navy,
                alignment: center,
                verticalAlignment: center,
                heightInPoints: 28
            }
        }
    ]]>
</excel>

用途：

做标题区、表头区高亮

7.2 数据列统一样式

<excel name="exportColumnStyle" returnClass="void">
    <![CDATA[
    EXPORT WITH
        SHEET="学生表",
        HEADER=true,
        STYLE={
            COL D: {
                alignment: right,
                borderBottom: thin,
                borderLeft: thin,
                borderRight: thin
            },
            COL E: {
                alignment: center,
                wrapText: true
            }
        }
    ]]>
</excel>

用途：

数值列右对齐
日期列或说明列统一样式

7.3 单元格重点标记

<excel name="exportCellStyle" returnClass="void">
    <![CDATA[
    EXPORT WITH
        SHEET="学生表",
        HEADER=true,
        STYLE={
            A1: {
                bold: true,
                fillPattern: solid_foreground,
                fillForegroundColor: red,
                color: white
            },
            D5: {
                bold: true,
                borderTop: double,
                borderBottom: double,
                alignment: center
            }
        }
    ]]>
</excel>

用途：

特殊标题格
汇总结果格
警示信息格

7.4 行高与隐藏行

<excel name="exportRowHeightStyle" returnClass="void">
    <![CDATA[
    EXPORT WITH
        SHEET="学生表",
        HEADER=true,
        STYLE={
            ROW 1: {
                heightInPoints: 32,
                bold: true
            },
            ROW 10: {
                zeroHeight: true
            }
        }
    ]]>
</excel>

用途：

拉高表头
隐藏辅助行

7.5 组合样式

<excel name="exportComplexStyle" returnClass="void">
    <![CDATA[
    EXPORT WITH
        SHEET="学生表",
        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
            }
        }
    ]]>
</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.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 字体颜色、边框颜色、填充颜色支持什么值？

当前是通过颜色枚举映射的，推荐使用常见英文颜色名，例如：

red
blue
yellow
green
white
black
navy

如果某个颜色名无效，优先换成常见基础色测试。

11.7 行样式为什么没有作用到空白单元格？

因为行样式只处理该行已经存在的单元格，不会自动把这一整行所有可能列都建出来。

如果你需要确保某个目标单元格一定被设置，建议直接用单元格样式。

12. 推荐实践

站在程序员角度，推荐这样使用 STYLE：

12.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/

声明式Excel样式编排：JQuick-Export STYLE 设计解析与30+配置属性详解

JQuick-Excel 导出 STYLE 配置项使用手册

目录

1. STYLE 是什么

2. 基础语法

3. 四类目标范围

3.1 行样式

3.2 列样式

3.3 单元格样式

3.4 区域样式

4. STYLE 的执行时机

5. 可用样式属性

5.1 字体类属性

5.2 对齐类属性

5.3 边框类属性

5.4 填充类属性

5.5 其他单元格属性

5.6 行专属属性

6. 最小可运行示例

7. 常见配置示例

7.1 表头高亮

7.2 数据列统一样式

7.3 单元格重点标记

7.4 行高与隐藏行

7.5 组合样式

8. STYLE 与 THEME / FORMULAS / TRANSFORM 的关系

8.1 与 THEME 的关系

8.2 与 FORMULAS 的关系

8.3 与 TRANSFORM 的关系

9. STYLE 与 SXSSF 流式导出的限制

10. 当前实现特性与注意事项

10.1 行样式只会作用于“该行已存在的单元格”

10.2 列样式会自动创建缺失单元格

10.3 单元格样式会自动创建行和单元格

10.4 RANGE 样式当前不会真正生效

10.5 dataFormat / dataFormatString 当前不建议通过 STYLE 使用

11. 常见问题与避坑指南

11.1 为什么我设置了背景色但没显示？

11.2 为什么 RANGE 样式写了没效果？

11.3 为什么用了 STYLE 后流式导出没生效？

11.4 ROW 1 是第 0 行还是第 1 行？

11.5 列目标应该写数字还是列字母？

11.6 字体颜色、边框颜色、填充颜色支持什么值？

11.7 行样式为什么没有作用到空白单元格？

12. 推荐实践

12.1 主题 + 局部样式覆盖，是最实用组合

12.2 表头优先用行样式

12.3 重点值优先用单元格样式

12.4 大数据导出尽量少用复杂 STYLE

12.5 先保证数据正确，再做视觉精修

10.5 `dataFormat` / `dataFormatString` 当前不建议通过 STYLE 使用

11.4 `ROW 1` 是第 0 行还是第 1 行？