jquick-pdf 表格行列尺寸控制实战：单元格合并的可行边界

引入

表格是报表 PDF 中最容易失控的部分：数值列太窄会折行，说明列过高会让整页行数不足，汇总信息又常被要求"合并居中"。用底层 iText/PDFBox 手写这类表格时，合并单元格意味着自行维护 rowspan/colspan 占位矩阵，列顺序一变，错位往往要等到输出 PDF 才被发现。

jquick-pdf 的处理方式是把几何信息交给模板样式，把结构交给标签。使用前必须先区分"已验证能力"和"未证实能力"：本地 sample 已验证 <table>、<tr>、<td>、<th> 以及 width、height 样式可以工作；rowSpan、colSpan 在现有源码与测试中没有被证实，因此本文不提供可运行的合并写法，而是给出可落地的替代布局。环境只说明一次：Maven 引入 io.github.paohaijiao:jquick-pdfx:4.0.0，JDK 8+ 即可运行本文全部代码。

核心讲解

三层尺寸：总宽、行高与列宽

一次表格渲染的几何由三层声明共同决定：

<table style="width:520px"> 声明表格总宽度；
<tr style="height:36px"> 声明行高，表头行与数据行可以分别设置；
<th style="width:160px"> 与 <td> 声明列宽。

建议的声明顺序是"先总宽、再分列宽、最后定行高"。列宽之和与总宽不一致时的实际表现（等比缩放、溢出还是忽略其一）属于实现细节，应以本地输出为准，不要凭 HTML 表格的经验推断。单位遵循 px（96 DPI，1px = 0.75pt）、pt、mm、cm、in，因此 520px ≈ 390pt ≈ 137.6mm，在 A4 纵向并保留常规页边距后仍有余量；60px 的数据行高等于 45pt。

固定行高在真实报表中的用途

固定行高解决的是"行的视觉节奏"而不是"内容高度"：多行说明文本折行时，只要行高一致，整页基线才统一，扫描式阅读不会跳动。演示中表头行取 36px 并配 #DDEAFE 底色形成层级，数据行取 60px 为两行说明文本预留空间。需要注意，行高一旦固定，内容超出时的处理方式（裁切、撑高还是推到下一页）依实现而定，因此长文本必须靠列宽与文本长度共同约束，而不能只靠行高。

列宽与内容挤压的关系

列宽本质是分配问题：总宽固定时，某一列变宽必然挤压其他列。最容易被挤压的是文本列------宽度不足触发折行，折行又推高该行，最终表现为表格整体变长、分页位置漂移。因此"编号列尽量窄、说明列尽量宽"是常见策略，同时应缩短表头文案（"说明"优于"变更说明与当前处理进展"），并在后端对超长字段先做截断或摘要，而不是指望渲染层自动收敛。

用 `div` 分组替代合并单元格

可行的替代思路有三条：

视觉分组：对需要横跨整表的信息，用带 border、padding、backgroundColor 的 <div> 独立成块，放在表格上方或紧随其后，语义上与"跨列单元格"等价；
空单元格加对齐：同一取值连续多行时留空重复值，配合 textAlignment、verticalAlignment 形成视觉连续；
汇总行整行输出：不合并，把汇总文案写进一列，另一列放数值。

演示采用第一种方式，用 <div style="border:1px solid #999;padding:8px"> 承载"合并展示：项目状态 / 进行中"。

关键细节

文本字面量必须用单引号包裹（'阶段'）；变量写作 ${name}，已注册资源写作 &{name}，模板根元素为 <pdf> 或 <html>；
样式属性名驼峰与连字符互为别名，backgroundColor 与 background-color 等价；
尺寸护栏：minWidth、maxWidth、minHeight、maxHeight 可用于异常内容保护，例如给说明列设置 maxWidth，但具体生效结果属实现细节，需实测确认；
边框与圆角：border 与四向边框按「类型宽度颜色」书写（如 solid 1px #999），borderRadius 可用于分组块的视觉区分；颜色支持颜色名、#RRGGBB、rgb()/rgba() 与 linear-gradient；
可读性：数字列可用 textAlignment 右对齐、表头居中，单元格内文本可用 verticalAlignment 调整垂直位置；
长文本影响的是视觉高度：固定 height 与长文本叠加时，先看输出 PDF，再决定缩短文本还是拆分表格；
跨页表现：文档具备自动分页与强制分页能力（<areaBreak>、<htmlPageBreak>）。固定行高跨页时，页尾剩余空间不足会把整行推到下一页，留下空白带，行高与页面可用高度不匹配会放大这段空白。建议行高取页面可用高度的约数，并把"续页是否重复表头"列入验收项。

实战说明

java 复制代码

import com.github.paohaijiao.executor.JQuickPdfFactory; // 导入工厂
import java.nio.file.Files; // 导入文件类
import java.nio.file.Paths; // 导入路径类

public class TableSizeDemo { // 声明类
    public static void main(String[] args) throws Exception { // 声明入口
        String template = "<pdf><body><h1>'项目进度'</h1>" // 创建模板
                + "<table style=\"width:520px\">" // 控制总宽度
                + "<tr style=\"height:36px;backgroundColor:#DDEAFE\">" // 控制表头行高和底色
                + "<th style=\"width:160px\">'阶段'</th><th style=\"width:360px\">'说明'</th></tr>" // 控制列宽
                + "<tr style=\"height:60px\"><td>'需求'</td><td>'已完成评审，进入开发。'</td></tr>" // 控制数据行高
                + "</table><div style=\"border:1px solid #999;padding:8px\">" // 用块模拟分组视觉
                + "<p>'合并展示：项目状态'</p><p>'进行中'</p></div></body></pdf>"; // 结束模板
        byte[] pdf = new JQuickPdfFactory().executeContent(template); // 执行渲染
        Files.write(Paths.get("table-size.pdf"), pdf); // 保存 PDF
    }
}

执行步骤与预期：

编译并运行 TableSizeDemo，在当前目录得到 table-size.pdf；
预期标题"项目进度"下出现两行表格：表头行高 36px 且带 #DDEAFE 底色，数据行高 60px；
预期阶段列（160px）明显窄于说明列（360px），正文"已完成评审，进入开发。"不折行；
表格下方出现带 1px 灰色边框的 div 分组块，内部两段文本分别表示分组标题与当前状态；
验证方式：用阅读器的测量工具检查实际列宽与行高是否接近声明值；用文本抽取确认单引号内的字面量完整出现；再换一个阅读器打开，确认外观一致；
回归检查：把说明文本换成长文本（例如再加三十个字）重跑一次，观察是否折行、表格总高增加了多少，用这个结果反推列宽是否需要调整。

异常排查：

行高未生效：检查 style 中属性拼写、单位是否带 px，以及是否写在了 <tr> 上；
列宽被压缩：缩短该列文本或减少列数，必要时调整总宽；
渲染报错或文本异常：检查字面量是否漏了单引号，模板根元素是否为 <pdf> 或 <html>。

生产环境还需注意：本方案适合项目进度、配置清单、审批摘要这类行列结构固定的报表；一旦出现"合计行跨列""行列由数据决定"的需求，应改用后端生成行加视觉分组的方式，而不是尝试未证实的合并属性。

总结

本文结论可以概括为三点。第一，表格几何由总宽、行高、列宽三层共同决定，应按"总宽 → 列宽 → 行高"的顺序声明，并用单位换算（1px = 0.75pt）预估是否适配页面。第二，固定行高服务的是视觉节奏，列宽决定内容是否被挤压，两者都必须与文本长度一起权衡，maxWidth 这类护栏只能作为保护而非排版方案。第三，rowSpan/colSpan 未获证实，涉及合并的需求应使用 div 分组、空单元格对齐或整行汇总来表达。

常见误区有两个：把未知属性写进模板后"不报错"当作"已支持"，以及在跨页场景下默认行高会被稳定保持。前者会在验收阶段暴露，后者会在长报表中暴露。

版本基线：jquick-pdfx 4.0.0、JDK 8+，升级前请核对 README_zh.md 的版本对照表，确认表格与样式相关行为是否变化；更多示例见 GitHub 仓库。

jquick-pdf 表格行列尺寸控制实战：单元格合并的可行边界