JQuick-Excel 复杂 STYLE 实战：把报表样式拆成可维护的坐标规则

JQuick-Excel 复杂 STYLE 实战：把报表样式拆成可维护的坐标规则

tags: #JQuickExcel #JavaExcel #开源 #POI #Excel工具

简介

我在做业务导出时，经常遇到一个误区：数据已经能写进 Excel，于是样式就被当成最后几行"顺手补上"的代码。真正投入使用的报表并非如此。表头需要让阅读者一眼识别层级，日期、数值和文本需要以不同方式呈现，长文本需要换行，边框需要界定区域，少数强调单元格又不能破坏整张表的秩序。本文只讨论 JQuick-Excel 的复杂 STYLE：我如何用行、列、单元格和矩形范围组织样式，并把样式、值转换和 Excel 显示格式分开处理。

JQuick-Excel 是一个用于导入、导出 xls 与 xlsx 工作簿的轻量 Java 框架。README-CN 已确认，它使用 XML 服务定义和声明式 DSL 组织字段映射、转换、校验、公式、样式、合并、图表和页脚。对我而言，STYLE 的价值不在于替代 Apache POI，而在于把报表视觉规则放回 XML：规则与 MAPPING、FORMAT、TRANSFORM 同处一处，能够随报表定义一起被阅读、评审和回归。

前言

复杂样式最容易失控的原因不是属性太多，而是没有先区分"共性"和"例外"。如果每一个单元格都单独声明字体、填充、边框与对齐，XML 会迅速变成长而不可读的坐标清单；如果只给整张表加一种样式，最终文件又无法支持实际的浏览和核对。我采用三层结构：第一层用表头建立信息层级，第二层用数据区建立稳定的扫描节奏，第三层只为真正的例外单元格或范围补充强调。

README-CN 明确说明，STYLE 接受行、列、单元格或范围目标。也就是说，ROW 1 可以覆盖整个表头，A2:E100 可以作为正文区域，D2:D100 可以控制某个数字列，A2 则可以精确处理单格例外。这是一个坐标契约，而不是字段名契约。它让我可以用大范围规则表达重复视觉语言，再用更小的范围补足局部需要；与此同时，它也要求我在调整 MAPPING 输出顺序后，主动复查受影响的坐标。

我不会把"美观"理解为更多颜色或更多边框。业务报表的目标是让人快速找到表头、对齐同类数据、分辨日期和数值、发现关键异常。通常，一行一致的表头、连续而克制的分隔边框、数字列的稳定对齐、日期的统一显示，比多种装饰色更有价值。复杂 STYLE 的重点是明确规则边界，不是制造视觉噪声。

在开始写 XML 前，我会先确定报表的阅读顺序：用户从哪一行开始认识列含义，哪些列需要横向比较，哪些列可能包含较长说明，哪些值是日期、整数或金额，哪些区域需要重点提示。随后我把这些判断翻译为范围：表头用行，正文用矩形，特定类型字段用列，例外才用单元格。这样做的好处是，即使以后增加数据行，样式的意图也仍然容易理解。

环境与依赖

本文以仓库现有事实为基础。项目 README-CN 给出的 Maven 坐标是 io.github.paohaijiao:jquick-excel，版本为 3.6.0；README-CN 同时标明运行环境为 Java 8 或更高版本，并支持 xls、xlsx 两种工作簿格式。项目的 pom.xml 已声明 Apache POI 的 poi 和 poi-ooxml 依赖，因此 JQuick-Excel 的导出能力建立在 POI 工作簿能力之上，但调用方不需要在每个报表入口重复编写 POI 样式对象代码。

<dependency>
  <groupId>io.github.paohaijiao</groupId>
  <artifactId>jquick-excel</artifactId>
  <version>3.6.0</version>
</dependency>

我把 XML 放在类路径资源中，使用 README-CN 展示的 JQuickXmlFactory 创建服务代理。导出时，Java 代码准备业务数据、转换为 JQuickRow、打开输出流并提供导出解析器；XML 中的 EXPORT WITH 负责工作表、表头、映射、样式等报表规则。这样的边界很重要：数据来源属于应用层，视觉结构属于报表定义，输出流生命周期属于 Java 的资源管理。

仓库测试资源 src/test/resources/jquick-excel.xml 已经展示了真实的样式写法。它在 STYLE 中对 ROW 1 设置 fontName、fontHeightInPoints、italic、color 和 bold。README-CN 还确认了对齐、自动换行、四方向边框、填充模式、填充色和 dataFormatString 等属性。因此，本文示例只使用这些已确认的 DSL 属性，不猜测未公开的名称或扩展语法。

代码示例

下面以学生表为例。示例保留项目测试 XML 已出现的中文工作表和字段风格，并把复杂样式划分为表头、正文、文本列、数值列、日期列和单元格例外六个层次。坐标中的第 1 行是表头，第 2 行起是数据；实际项目应根据自己的数据量调整下界和上界。

<excel name="exportExcel" returnClass="void"><![CDATA[
EXPORT WITH
SHEET="学生表",
HEADER=true,
MAPPING={
  "id":"主键",
  "name":"姓名",
  "gender":"性别",
  "age":"年龄",
  "enrollmentDate":"入学时间"
},
STYLE={
  ROW 1:{
    fontName:Arial,
    fontHeightInPoints:12,
    italic:true,
    color:yellow,
    bold:true,
    alignment:center,
    verticalAlignment:center,
    fillPattern:solid_foreground,
    fillForegroundColor:lightYellow,
    borderBottom:thin
  },
  A2:E100:{
    verticalAlignment:center,
    borderBottom:thin
  },
  B2:B100:{
    wrapText:true
  },
  D2:D100:{
    alignment:center,
    dataFormatString:"0"
  },
  E2:E100:{
    alignment:center,
    dataFormatString:"yyyy-MM-dd"
  },
  A2:{
    bold:true,
    borderLeft:thin,
    borderRight:thin
  }
}
]]></excel>

Java 侧沿用 README-CN 的标准导出路径。下面的 students 是业务数据集合，JObjectConverter 将数据转成框架可使用的形式，JQuickRow.toRows 形成行集合。服务接口必须与 XML namespace 所指定的接口保持一致；示例中的方法参数沿用 README-CN 的调用形式。

import com.github.paohaijiao.convert.JObjectConverter;
import com.github.paohaijiao.statement.JQuickRow;
import com.github.paohaijiao.xml.JQuickFactory;
import com.github.paohaijiao.xml.JQuickXmlFactory;
import com.github.paohaijiao.xml.parse.JQuickParseHandler;
import com.github.paohaijiao.xml.parse.excel.JQuickExcelExportXmlParseFactory;

import java.io.FileOutputStream;
import java.io.OutputStream;
import java.util.List;

List<JQuickRow> rows = JQuickRow.toRows(JObjectConverter.convert(students));
try (OutputStream output = new FileOutputStream("students.xlsx")) {
    JQuickParseHandler parser = new JQuickExcelExportXmlParseFactory(rows, output);
    JQuickFactory factory = new JQuickXmlFactory(parser, "jquick-excel.xml");
    JQuickExcelExportService service = factory.createApi(JQuickExcelExportService.class);
    service.exportExcel("field", "value");
}

我会先用很小的数据集验证这个 XML。至少准备一行普通姓名、一行较长姓名或说明文本、一行整数年龄、一行日期值，以及一行空值。第一轮检查表头是否全部加粗、居中和填充；第二轮检查正文的底边框是否连续；第三轮检查姓名长文本是否换行、年龄是否仍显示为整数、日期是否显示为 yyyy-MM-dd；最后检查 A2 的例外样式没有覆盖相邻单元格。复杂样式的正确性不能只靠 Java 编译结果判断，必须打开生成文件复核。

若数据行数超过示例范围，我不会期待 A2:E100 自动扩展到无穷行。范围是显式坐标，所以要让它覆盖预计数据区域，或按报表规模调整规则。README-CN 还提供了 JQuickExcelConfig 的样式缓存开关和流式导出配置。它们服务于大数据场景，但不改变 STYLE 的语义；我会先让样式规则正确，再针对实际数据量决定是否启用相应配置。

原理说明

STYLE 的左侧是目标范围，右侧是属性集合。README-CN 已列出四类目标：行、列、单元格和矩形范围。行规则适用于横向一致的表头或汇总行；列规则适用于同一数据类型的展示要求；单元格规则适用于真正的例外；矩形范围适用于正文基线和块状区域。我通常优先选择能够覆盖共性的最大合理范围，因为规则越少，后续字段调整时遗漏的机会越少。

字体类属性承担信息层级。fontName 指定字体族，fontHeightInPoints 设定磅值字号，bold 和 italic 表达字形强调，color 设置字体颜色。项目测试资源已经使用 Arial、12、italic:true、color:yellow、bold:true 的组合。表头使用这些属性的目的不是堆砌效果，而是把标题行和数据区区分开，让阅读者在滚动或横向比对时仍能迅速定位列意义。

布局类属性决定内容是否容易扫描。alignment 用于水平对齐，verticalAlignment 用于垂直对齐，wrapText 用于自动换行。对于姓名、说明、地址等可能较长的文本，我倾向于只在对应列开启 wrapText，而不对所有数据区一概开启。对整数、日期等适合比较的数据，我会使用一致的对齐方式。这样做并不是规定某一种唯一布局，而是让同一列的视觉行为稳定，避免用户在不同记录之间重新适应。

边框类属性包括 borderLeft、borderRight、borderTop、borderBottom。README-CN 已列出 none、thin、medium、dashed、dotted、thick、double 等边框名称。我在普通业务表中常用 thin 作为数据区的底部分隔，因为它能提供行间定位而不显得拥挤；对于需要强调的边界，再考虑左右边框或更强的线型。边框应该服务于分组和对齐，不应该取代空白、标题层级和列顺序。

填充属性由 fillPattern、fillForegroundColor、fillBackgroundColor 组成。README-CN 已确认 no_fill、solid_foreground、fine_dots、sparse_dots、thin_horz_bands、thin_vert_bands 等模式。示例选择 solid_foreground 与 lightYellow，目的只是让表头形成稳定背景。实际项目中，我会控制填充的使用范围：通常表头、汇总行或明确状态区域可以使用，而普通数据区保持克制能减少视觉疲劳。

dataFormatString 是复杂样式中最容易被误用的属性。它属于单元格显示格式，负责把已经写入的日期或数值以某种形式展示。例如 yyyy-MM-dd 用于日期展示，0 用于整数展示。它不负责把任意原始值变成日期或数字，也不负责字典翻译、文本拼接或数值计算。README-CN 已清楚区分 FORMAT 与 TRANSFORM：前者控制最终 Excel 显示，后者在导入或导出前计算表达式。我也按这个边界处理问题：值不对先查 TRANSFORM 或数据准备，值对但显示不对再查 FORMAT 或 dataFormatString。

范围规则与 MAPPING 的关系也必须说清楚。MAPPING={"id":"主键","name":"姓名",...} 决定输出字段和表头排列；D2:D100 则表示输出后的第四列，从第二行到第一百行。STYLE 不会自动理解"年龄"这个字段名。如果我把 gender 和 age 的映射顺序交换，原先指向年龄的 D 列可能已经变成性别列。每次改动 MAPPING，我都会把样式、公式、合并和图表中涉及坐标的规则一起审查。

复杂表格的另一个常见问题是样式数量膨胀。README-CN 提供 setCellStyleCacheEnabled(true)，说明框架支持样式缓存配置。我的规则是尽量让一整列或一个矩形区域共享同一套属性，不根据每条数据拼接新的颜色、边框或格式组合。只有业务上真正不同的状态才应产生不同样式。这样既保持 XML 简洁，也减少工作簿中大量唯一样式组合带来的成本。

我还会把视觉规则与主题能力区分开。README-CN 说明 JQuick-Excel 提供 42 个内置导出主题，并可在 JExcelExportModel 上设置主题。主题适合提供整份工作簿的整体风格，STYLE 则适合精确处理某一行、列或范围。两者可以共同存在，但本文的重点是坐标级 STYLE；我不会把主题名称当作 STYLE 属性，也不会用大量局部样式去模拟一个本可由主题解决的全局风格问题。

从测试角度看，样式规则需要同时做结构核对和视觉核对。结构核对包括 XML 是否符合已确认 DSL、坐标是否覆盖预期区域、MAPPING 是否与坐标一致；视觉核对包括打开生成文件后检查字体、边框、填充、换行和日期显示。对于长期维护的报表，我会保存最小样本和边界样本，字段顺序或范围调整后重新生成。这样可以尽早发现"数据正确但列样式错位"这一类不会在编译时出现的问题。

注意事项

第一，坐标范围依赖最终输出列顺序。新增、删除或交换 MAPPING 中的字段后，我会同步检查 STYLE、FORMULAS、MERGE、GRAPH 中所有 A1 风格坐标。不能因为 XML 仍能解析就认为报表语义仍正确。特别是把一个日期字段移动到其他列后，旧的 dataFormatString:"yyyy-MM-dd" 可能会落在无关列上。

第二，只使用 README-CN 已确认的属性和值。边框可使用 thin、medium、dashed、dotted、thick、double 等，填充可使用 solid_foreground 等。属性名、花括号、逗号和范围写法都是 DSL 的一部分。我不会根据 POI 的 Java 常量名猜测 XML 中的写法，更不会把未经确认的属性直接写入生产规则。

第三，自动换行并不等于所有内容都会天然适合阅读。长文本、空文本、混合语言和极长单词都会影响最终行高与列宽。JQuick-Excel README-CN 确认了 wrapText:true，但具体版式仍要用真实数据打开文件检查。对于信息密度高的业务表，我会让说明字段换行，关键编号和数值字段保持稳定宽度，避免一行内容撑破整张表的横向扫描节奏。

第四，不要让 STYLE 承担数据清洗。日期字符串不规范、年龄需要计算、编码需要翻译时，应使用 TRANSFORM 或 Java 数据准备；单元格只需按格式展示时，使用 FORMAT 或 dataFormatString。将三者混用会让后续维护者无法判断某个变化是值变了、显示变了，还是视觉规则变了。

第五，大数据报表需要控制样式重复。README-CN 已提供流式导出、样式缓存和相关阈值配置。复杂 STYLE 并不意味着每一行都要有一套独立属性；恰恰相反，我会把共性提升到行、列和矩形范围，让样式缓存能够复用。对于真正的异常标记，也优先采用有限集合的固定规则，而不是依据每条记录动态构造无限组合。

第六，视觉验收不能省略。我至少检查表头是否可识别、数据区边框是否连续、长文本是否可读、数值与日期是否清晰、空值是否破坏布局、例外单元格是否越界。若报表同时面向 xls 与 xlsx，我会按实际交付格式打开生成文件检查。README-CN 确认框架支持两种格式，但每一份具体报表仍应以真实模板、真实数据量和实际使用工具进行回归。

第七，样式规则应保持稳定的命名和组织顺序。虽然 XML 不要求我给每条 STYLE 写注释，但我会按表头、正文、列级格式、例外单元格的顺序排列，避免无序插入。规则排列本身不能替代最终效果，却能让代码评审者迅速理解哪一条在控制哪个区域，也能降低后续坐标覆盖关系被误读的风险。

总结

复杂样式先划分阅读层级，再定义坐标范围：表头建立识别，正文维持一致性，列级规则处理换行和数据展示，单元格级规则只处理少量例外。样式、转换与格式各自负责不同的问题，避免把视觉规则混进数据计算。

模板变更应随 MAPPING 的输出顺序一起审阅。用包含长文本、日期、负数和异常状态的样本检查边框、对齐、换行与打印效果，才能确认坐标没有随着列调整而漂移。可维护的报表并不依赖堆砌属性，而依赖规则范围和例外原因都足够明确。