PDF 表格样式优化：jquick-pdf 边框、圆角、背景色
引入
报表的可读性往往不取决于数据量，而取决于视觉层次：哪里是表头，哪里是数据，行与行之间靠什么分隔。用 iText 或 PDFBox 实现边框、填充和圆角时，通常需要直接操作绘制对象，样式改动会渗入业务代码。jquick-pdf 允许在元素 style 中声明这些样式，把报表的视觉调整留在模板层。本文围绕表格与单元格的边框、背景色、下边框分隔线以及圆角的实现方式展开。
核心讲解
表格与单元格的边框、背景色
<table> 与单元格都支持 border、borderTop、borderRight、borderBottom、borderLeft 以及 backgroundColor。边框写法为「类型 宽度 颜色」，例如 border:solid 1px #999；backgroundColor 接受颜色名、#RRGGBB、rgb()/rgba() 和 linear-gradient。尺寸相关属性 width、height 可用于表格和单元格，minWidth、maxWidth 等可用于限制范围。
表头的视觉区分
表头与数据行通常靠两件事区分：底色和文字样式。给表头行设置 backgroundColor，再配合 fontColor、bold、textAlignment，即可形成清晰分层；数据行则通过单元格底色增强可读性。
下边框作为分隔线
行间分隔比整格描边更常见：只给单元格设置 borderBottom:1px solid #CBD5E1，就能得到轻量的横向分隔线，同时避免表格出现密集网格。这是样式与可读性的取舍——边框越少，视觉噪声越低，但越依赖底色与对齐来区分列。
table 与 div 的分工
样式放在哪一层，决定了后续改动的成本：表格负责列宽与整体宽度，单元格负责内边距、下边框与行内底色，外层 <div> 负责外框、圆角与大块留白，标题则用 fontSize、bold 与 fontColor 单独控制。按这个分工书写样式，视觉调整大多只改一处；反之，把外框和圆角直接写在表格上，容易同时触发列宽变化。
表格宽度与列宽控制
表格宽度用 width 声明，例如 width:500px，需要限制伸缩范围时可以配合 minWidth、maxWidth。单元格的 padding 同时影响行高与呼吸感：过小会让文字贴住边框，过大会增加行数与页数。列宽由内容与表格宽度共同决定，因此同一列的文本长度差异过大时，应优先统一格式化（对齐小数位、统一日期格式），而不是反复调整 width。
用外层 div 实现圆角
borderRadius 及四角单独圆角属性已经可用，但表格自身的圆角呈现需要以实际 PDF 输出为准；稳妥做法是用外层 <div> 承载 border、borderRadius 与 padding，把表格放在其中，让圆角由外层块保证。表格自身的圆角支持有限，不要把它当作确定效果来设计版式。
依赖
样式能力属于文档层，只需引用 jquick-pdfx；jquick-pdf-svg、jquick-pdf-font 等模块与表格样式无关，按需追加即可。
关键细节
颜色与单位
颜色可写颜色名、#RRGGBB、rgb()/rgba() 与 linear-gradient；rgba() 配合 opacity（取值 0~1）可用于弱化辅助信息。尺寸单位支持 px、pt、mm、cm、in。color 与 fontColor 在不同示例中都出现过，本文统一使用语义明确的 fontColor。属性名支持驼峰与连字符互为别名，同一份模板应保持统一写法。
可读性与打印
避免过深的背景配黑色文字，backgroundColor 与 fontColor 之间要留足对比度；打印场景应使用高对比度颜色，因为浅灰底色在纸面上可能几乎不可见。样式服务于阅读顺序，而不是装饰，表格的层级信息不宜超过三层。
样式与可读性的取舍
样式密度是影响可读性的主要变量：全网格、深色表头与斑马纹同时使用时，表格会显得拥挤，读者反而更难横向定位。常见做法是保留表头底色与一条横向分隔线，其余交给留白和对齐；合计行可以用 backgroundColor 配合 bold 强调，但应避免与表头同色，以免层级混淆。opacity 可用于弱化辅助信息，取值 0~1，不过打印时会进一步降低对比度，需要实测。
边框与圆角的写法
边框简写建议按仓库示例使用「类型 宽度 颜色」，例如 border:solid 1px #999；本文示例沿用了 1px solid #4F46E5 的原始写法，建议在目标版本上确认渲染结果。四角圆角可以分别指定，边框也可以拆成 borderTop、borderRight、borderBottom、borderLeft 单独设置，例如只给表头保留下边框。
常见误区
- 用表格描边模拟卡片：外框、圆角与内边距应交给外层 div。
- 给每个单元格都加四边边框，导致网格过密、打印发灰。
- 直接假定表格自身的圆角一定生效，而未在目标版本上验证输出。
典型配置问题与修正
- 把
borderRadius直接写在<table>上 → 表格自身的圆角支持有限，输出可能仍是直角；修正为把border、borderRadius与padding移到外层<div>，表格只保留width。 - 表格与每个
<td>同时设置border→ 线与线叠加，出现双线或粗细不均；修正为表格保留外框，单元格只保留borderBottom作为行分隔。 - 表头使用深色底配黑色文字 → 对比度不足，打印后难以辨认；修正为浅色底配深色文字，或深色底改配白色文字。
实战说明
依赖
<dependency>
<!-- 文档层核心：模板解析与 PDF 渲染 -->
<groupId>io.github.paohaijiao</groupId>
<artifactId>jquick-pdfx</artifactId>
<version>4.0.0</version>
</dependency>
环境为 JDK 8+。
TableStyleDemo
import com.github.paohaijiao.executor.JQuickPdfFactory;
import java.nio.file.Files;
import java.nio.file.Paths;
public class TableStyleDemo {
public static void main(String[] args) throws Exception {
String template = "<pdf><body>"
// 外层 div 承载边框、圆角与内边距
+ "<div style=\"border:1px solid #4F46E5;borderRadius:8px;padding:10px\">"
// 表格只负责列宽
+ "<table style=\"width:500px\">"
// 表头行设置底色
+ "<tr style=\"backgroundColor:#E0E7FF\"><th>'指标'</th><th>'数值'</th></tr>"
// 单元格用下边框做分隔线，数值列加浅底色
+ "<tr><td style=\"borderBottom:1px solid #CBD5E1\">'收入'</td>"
+ "<td style=\"backgroundColor:#F8FAFC\">'128000'</td></tr>"
+ "</table></div></body></pdf>";
// 渲染模板并保存 PDF
byte[] pdf = new JQuickPdfFactory().executeContent(template);
Files.write(Paths.get("table-style.pdf"), pdf);
}
}
效果图
步骤与输出
步骤是：先用外层块承载圆角与内边距，再给表头和单元格设置背景与边框，最后用阅读器检查颜色和线宽。顺序不宜颠倒——外层容器决定可用宽度，先定外层再调单元格，改动次数最少。输出为带紫色外框的圆角卡片、浅色表头和横向分隔线。
场景与选型
这套样式适合经营看板、财务汇总和客户交付报告：结构固定、层级清晰、以可读性优先。若需要更复杂的视觉分层，应优先增加留白与字号层次，而不是叠加更多边框和深色底；对外交付或打印的报表，用色数量应保持克制，并预留足够的行间距。
验证与回归
样式类改动建议用阅读器逐项核对：边框线宽与颜色是否与设计一致，圆角是否完整，浅色底在打印预览下是否仍可分辨。颜色与线宽在屏幕上差异小、在纸面上差异大，因此涉及打印的报表要额外做一次纸面检查。若同一套样式被多个报表复用，可以把骨架模板作为基线，改动后对比截图，避免某次调整影响其他报表。
总结
表格样式优化的关键结论是：边框、背景色与表头样式都写在元素 style 上，用下边框替代整格描边可以显著降低视觉噪声，圆角则交给外层 <div> 承载。样式写在模板上，既保留了 HTML 的可读性，也避免业务代码被绘制细节淹没。
需要注意的边界是：表格自身的圆角支持有限，必须以实际 PDF 输出为准；color 与 fontColor 的写法在示例中并不统一，建议统一使用 fontColor；深色背景配黑字与浅灰打印底色都是常见的可读性陷阱。升级前应复核 CSS 属性的解析结果，确认边框、圆角与背景色的表现没有变化。
版本基线：jquick-pdfx 4.0.0、JDK 8+，升级前请核对 README_zh.md 的版本对照表；更多示例见 GitHub 仓库。
