Flying Saucer设置背景图时首页空白问题排查与解决

问题原因 #

Flying Saucer的页面渲染逻辑中，默认会先初始化一个空白的默认页面。当第一个内容元素直接通过page属性指定自定义页面类型时，它会在这个初始空白页面之后创建新的自定义页面来承载内容，从而导致出现空白首页。

解决方法 #

方案一：设置默认页面为带背景样式，按需切换 #

通过将带背景的页面设为默认页面，仅在需要无背景的页面切换回默认空白页面，避免初始页面留白：

修改后的CSS代码

@page {
  /* 定义无背景的默认页面，可按需调整边距 */
  margin: 2cm;
}

@page with-bg {
  background-image: url("img/a4_wallpapper.png");
  background-size: cover;
  margin: 2cm; /* 保持与默认页面边距一致，防止内容偏移 */
}

/* 让body默认使用带背景的页面，覆盖前两页 */
body {
  page: with-bg;
}

.page-break-before {
  page-break-before: always;
}

/* 第三页切换回无背景的默认页面 */
.no-bg {
  page: auto;
}

修改后的HTML结构

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <style>
        /* 上述CSS代码 */
    </style>
</head>
<body>
<div>
    <h1>First Page</h1>
</div>
<div class="page-break-before">
    <h1>Second Page</h1>
</div>
<div class="page-break-before no-bg">
    <h1>Third Page</h1>
</div>
</body>
</html>

方案二：使用页面伪类指定前两页背景 #

通过@page :first和自定义页面规则直接为前两页设置背景，无需切换页面类型，避免触发初始空白页面：

修改后的CSS代码

@page {
  margin: 2cm;
}

/* 第一页设置背景 */
@page :first {
  background-image: url("img/a4_wallpapper.png");
  background-size: cover;
}

/* 第二页使用的带背景页面规则 */
@page second-page {
  background-image: url("img/a4_wallpapper.png");
  background-size: cover;
}

.second-page {
  page: second-page;
}

.page-break-before {
  page-break-before: always;
}

修改后的HTML结构

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <style>
        /* 上述CSS代码 */
    </style>
</head>
<body>
<div>
    <h1>First Page</h1>
</div>
<div class="second-page page-break-before">
    <h1>Second Page</h1>
</div>
<div class="page-break-before">
    <h1>Third Page</h1>
</div>
</body>
</html>

内容的提问来源于stack exchange，提问作者CodeWizard1985