页边距与页眉页脚

HTML 转换 PDF 时，可以通过 CConverterProperties 设置页边距，并在每一页的上下边距区域内绘制独立的 HTML 页眉页脚。页码、总页数等内容在分页后自动计算，无需逐页设置。

设置页边距

页边距的单位为 CSS 像素（px），顺序为上、右、下、左。HTML 正文中通过 @page 显式指定的边距优先于此处的设置。未设置时边距为 0。

CConverterProperties properties = new CConverterProperties();
properties.SetPageSize(new CSize { Width = 595, Height = 842 });

// 设置页边距，任一值为负数时返回 false，原有设置保持不变
properties.SetPageMargins(new CPageMargins { Top = 35, Right = 0, Bottom = 42, Left = 0 });

// 读取当前的页边距
CPageMargins margins = properties.GetPageMargins();

添加页眉页脚

页眉页脚通过 CHeaderFooterOptions 配置，模板为 HTML 片段。模板中带有以下 class 的元素会被自动替换为对应的内容：

class	填充内容
`date`	日期。未设置 `Date` 时使用本次转换的本地日期时间，格式为 `YYYY-MM-DD HH:MM`
`title`	标题。未设置 `Title` 时使用正文的 `<title>`
`url`	地址。HTML 字符串没有固有地址，需要通过 `Url` 提供
`pageNumber`	当前页码，从 1 开始
`totalPages`	总页数，不包括被排除编号的前导页

CConverterProperties properties = new CConverterProperties();
properties.SetBaseUri("/baseUri/");
properties.SetPageSize(new CSize { Width = 595, Height = 842 });
// 页眉页脚绘制在上下页边距内，需要为其预留足够的空间
properties.SetPageMargins(new CPageMargins { Top = 35, Right = 0, Bottom = 42, Left = 0 });

CHeaderFooterOptions options = new CHeaderFooterOptions();
// 总开关，默认为 false，关闭时忽略模板
options.DisplayHeaderFooter = true;

// 空字符串使用内置的默认模板，"<div></div>" 表示显式留空
options.HeaderTemplate = """
    <div style="height:25px;background:linear-gradient(#6097c7 41%,#fff 40%)"></div>
    """;
options.FooterTemplate = """
    <div style="position:relative;height:42px;font-family:DroidSansFallback;font-size:8pt;line-height:14px">
        <div style="position:absolute;left:24.3%;top:2px;white-space:nowrap">
            本報表內容僅供參考，詳細內容請參閱所屬保險公司的保單條款為準!
        </div>
        <div style="position:absolute;right:0.6cm;top:2px;white-space:nowrap">
            製表日期：<span class="date"></span>
        </div>
        <div style="position:absolute;left:32px;bottom:1px;font-size:7.5pt;color:#707070">
            第<span class="pageNumber"></span>頁/共<span class="totalPages"></span>頁
        </div>
    </div>
    """;

// 模板中图片、样式等相对资源的基准目录，为空时使用正文的资源目录
options.BaseUri = "/templateDir/";
// 覆盖正文的 <title>
options.Title = "家庭保單健診報告";
// 固定日期，为空时使用本次转换的本地日期时间
options.Date = "2026/9/23";

// 第一页作为封面：不显示页眉页脚，也不参与页码计算
options.SkipLeadingTemplatePages = 1;
options.SkipLeadingNumberedPages = 1;

// 跳过页数为负数时返回 false
properties.SetHeaderFooterOptions(options);

CHtmlConverter.ConvertToPdf("/htmlFile.html", "/headerFooterOut.pdf", properties);

使用默认模板

模板为空字符串时使用内置的默认模板：页眉显示日期和标题，页脚显示地址和"页码/总页数"。

CHeaderFooterOptions options = new CHeaderFooterOptions
{
    DisplayHeaderFooter = true,
    Url = "https://www.compdf.com"
};
properties.SetHeaderFooterOptions(options);

仅显示页脚

将页眉设置为 "<div></div>" 即可只显示页脚。如果设置为空字符串，将使用默认模板。

CHeaderFooterOptions options = new CHeaderFooterOptions
{
    DisplayHeaderFooter = true,
    HeaderTemplate = "<div></div>",
    FooterTemplate = "<div style='font-size:9pt;text-align:center'>- <span class='pageNumber'></span> -</div>"
};
properties.SetHeaderFooterOptions(options);

跳过前导页

SkipLeadingTemplatePages 和 SkipLeadingNumberedPages 相互独立：

SkipLeadingTemplatePages：前 N 页不绘制页眉页脚。
SkipLeadingNumberedPages：前 N 页不参与编号，这些页的 pageNumber 为空，totalPages 也不包括这些页。

例如，文档共 35 页，两者都设置为 1 时，封面没有页眉页脚，第二页显示 1/34，最后一页显示 34/34；只设置 SkipLeadingTemplatePages = 1 时，第二页显示 2/35。

注意事项

模板是独立的 HTML 文档，不继承正文的 CSS，也不执行 JavaScript，请在模板中使用内联样式。
模板的宽度为页面宽度减去左右边距；页眉顶端与纸张顶部对齐，页脚底端与纸张底部对齐，如需与纸张边缘保持距离，请在模板中设置 padding。
模板内容超出上下边距区域时转换失败，请增大页边距或缩小模板内容。
模板中的中文可以使用 SDK 内置的 DroidSansFallback 字体显示，无需额外加载字体。
独立页眉页脚不能与正文中作为重复页眉页脚的 <header>、<footer> 同时使用，否则转换失败。
页眉页脚字符串在设置时被复制，之后修改 CHeaderFooterOptions 对象不会影响已设置的内容。

页边距与页眉页脚 ​

设置页边距 ​

添加页眉页脚 ​

使用默认模板 ​

仅显示页脚 ​

跳过前导页 ​