22 背景色与背景图片：元素级背景的配置与边界
引入
企业报告常需要统一品牌底色、封面纹理或页内浅色衬底。如果把背景逻辑散落在每个节点里，样式难以维护，换主题时要逐处修改。jquick-pdf 的样式模型中，backgroundColor 与 backgroundImage 是元素级属性，已在 style3.txt 验证。本文说明这两个属性的写法、它们与“全局分页背景”的区别，以及资源与打印方面的边界。
环境与依赖见第 21 篇（jquick-pdfx 4.0.0、JDK 8+）。另需准备一张可读的背景图 background.png，比例按 A4 页面设计。
核心讲解
两个背景属性
backgroundColor：元素背景填充色，取值与颜色体系一致——颜色名（lightgray、red）、#RRGGBB、rgb()/rgba()、linear-gradient。backgroundImage：背景图片路径，已验证写法为backgroundImage:'D:/pdf/image.png'，值是资源路径。
两者可以同时写在一个元素的 style 上。图片正常加载时显示图片，加载失败时颜色仍然可见，颜色天然承担兜底角色。
backgroundColor 的取值遵循统一颜色体系，除颜色名、#RRGGBB 和 rgb() / rgba() 外，linear-gradient 也可用于背景。渐变是否被当前解析器接受、方向与起止色如何解析，应以生成结果确认，不要先按浏览器效果假设。
用背景色组织页面分区
不引入全局背景时，可以给不同的块各自设置 backgroundColor 形成分区：封面块用品牌深色，正文块保持白底，附录块用浅灰。背景随内容一起流动，天然适合长文档；代价是每页观感由该页内容决定，页面尾部可能留白。要求每一页底色完全一致时，就必须按页生成结构，而不是依赖某一个块的背景。
元素背景不等于全局分页背景
已验证的是元素 style 语法，即“这个元素有背景”，不等同于“自动给每一页设置背景”。因此统一背景要这样组织：放在 <body> 内的首个块或页面模板中，由业务代码为每页复用同一段结构。真正的页眉、页脚、水印级背景需要结合项目配置或事件 API 逐项验证，不要按元素背景的结论外推。
完整示例
import com.github.paohaijiao.executor.JQuickPdfFactory;
import java.nio.file.Files;
import java.nio.file.Paths;
public class BackgroundDemo {
public static void main(String[] args) throws Exception {
String image = "src/main/resources/image/background.png";
String template = "<pdf><body>"
// 固定尺寸、带内边距的内容块承载背景
+ "<div style=\"backgroundColor:lightgray;backgroundImage:'" + image + "';"
+ "width:520px;height:700px;padding:30px\">"
+ "<h1>'年度经营报告'</h1><p>'统一背景区域中的正文内容'</p>"
+ "</div></body></pdf>";
byte[] pdf = new JQuickPdfFactory().executeContent(template);
Files.write(Paths.get("background-report.pdf"), pdf);
}
}
关键细节
尺寸决定背景铺满范围
背景铺在元素的盒子内：width、height 建立稳定画布，内容不足时背景仍按设定尺寸渲染，内容超出时背景不会自动扩展到内容之外。固定尺寸适合封面；长正文块不要写死高度，否则分页处会出现背景中断。若希望背景随内容走，可以不设高度、让内容撑开盒子，但要接受不同数据下背景范围不一致。
用 minHeight、maxHeight 可以给范围加约束：minHeight 让短内容也有统一的底色高度，maxHeight 则会把超出部分挡在盒子之外，需要确认内容是否溢出。同一份模板在不同数据长度下的表现不一致时，优先检查尺寸约束而不是背景属性本身。
背景与内容的层叠顺序
背景属性画在元素自身的盒子里，正文是该元素的内容，两者天然不冲突。但如果为了做遮罩或水印而在同一位置额外放一个块，块的先后顺序写错就会遮住文字。这类问题属于模板结构问题，不是样式解析问题，排查时先看结构再看属性。
缺图时的兜底
backgroundColor 负责兜底，backgroundImage 是可选增强。路径不可读时（写错、文件被删、打包后资源未随包发布），颜色仍可能显示，因此“看起来有背景”不代表图片加载成功，上线前应主动检查资源。
路径与资源
backgroundImage 的值是文件路径，已验证的是本地路径写法，未证明支持网络地址。相对路径相对于进程工作目录，不一定是源码目录；Windows 路径的反斜杠要正确转义，建议统一用 /。值含引号时要与 Java 字符串转义配合。把背景图作为 classpath 资源发布时，还要确认打包流程包含该文件，否则会出现测试环境正常、生产环境缺图。
颜色名称的解析范围
颜色名的支持范围以当前解析器与已验证示例为准，不要假设浏览器支持的全部颜色名都被识别；拿不准时改用 #RRGGBB 更可靠。
多页复用的组织方式
业务代码可以用一个方法生成“页面块”片段（背景 + 内边距 + 内容占位），循环拼接成多页结构；模板层面也可以用 <template> 元素组织重复片段，避免逐页复制粘贴。复用同一段结构时要注意各页数据长度不一致会改变背景范围，验收要覆盖最短页与最长页两种极端情况。
与页眉页脚的分界
背景样式与页眉、页脚、水印、目录是不同的能力。水印通常需要独立配置，目录由文档结构生成。把它们和背景混在同一段 style 里，后续调整会互相牵制；建议分主题管理、分别验证。
图片尺寸与体积
背景图太小会被平铺或形成重复观感，比例与元素不匹配会产生留白；图片太大会显著增加 PDF 体积。按 A4 比例预处理图片，并控制像素与字节数。
多页背景的性能
每一页都铺一张背景图时，文件体积和渲染耗时都会上升，图片未压缩时尤其明显。多页背景应复用同一份图片资源并预先压缩，长文档先测页数与生成耗时再上线；如果只是需要统一底色，用 backgroundColor 比铺图更轻。
实战说明
步骤
- 确认背景图存在且路径可读，统一用
/分隔。 - 建立
<pdf><body>骨架，把背景放到 body 内首个块或每页的页面块上。 - 同时写
backgroundColor与backgroundImage，颜色兜底。 - 用
width/height稳定画布，用padding让文字不贴边。 - 执行
executeContent并写出 PDF。
多页报告在每个页面块复用这套结构，或在业务代码中生成统一模板片段，避免逐页手写。
验证与结果预期
- 把图片改名后重新生成，确认背景色兜底生效——这一步能区分“图片真的加载了”和“只是颜色在显示”。
- 检查内容块四周是否有留白或溢出。
- 用 A4、Letter 两种尺寸各跑一次，观察分页处背景是否被截断。
- 相对路径与绝对路径各跑一次，确认路径解析基准符合预期。
- 多页文档分别检查最短页与最长页的背景范围是否一致。
- 若使用渐变背景，先用最小模板单独验证解析是否通过。
- 核对文件大小是否符合预期。
结果预期：首页显示带背景的标题区与正文，浅灰底色在图片缺失时仍然可见，多页文档的每页背景范围一致。
与图片元素的分工
需要精确控制图片位置与尺寸时，用 <image> 元素按图片主题的方式摆放更可控；backgroundImage 适合整块衬底。两者不要在同一元素上混用，否则层叠关系难以判断。
打印差异
打印时背景默认可能不显示，阅读器与打印机常默认关闭背景图形，这与渲染结果无关。若文档依赖底色传达信息，关键文字要用深色以保证无背景时仍可读，避免“浅色字配深色底”这种强耦合设计。
生产注意事项
建立品牌主题对象，统一输出颜色、背景路径和尺寸，避免颜色常量散落在模板字符串里；对背景图压缩并缓存；导出前做文件存在性与像素检查；长报告把背景块拆成可分页结构并专门测试页边界。背景样式与页眉、页脚、水印、目录属于独立能力，应分开测试。
总结
backgroundColor 与 backgroundImage 是元素级背景属性，可组合使用，颜色承担兜底。关键边界是：元素背景不等于全局分页背景，统一背景要靠在 body 首个块或每页页面块上复用结构实现。背景范围由元素尺寸决定，图片路径必须是可读的本地资源，打印时背景显示还取决于阅读器设置。
常见误区是看到颜色就以为图片加载成功、或用固定高度的盒子承载跨页正文导致背景中断。用背景色兜底、图片可选的设计更适合生产。
版本基线：jquick-pdfx 4.0.0、JDK 8+，升级前请核对 README_zh.md 的版本对照表；更多示例见 GitHub 仓库。
