如何在TCPDF中插入页眉Logo并解决HTML元素不显示问题

1. 页眉添加 Logo 的实现方法 #

TCPDF 默认自带页眉方法，你需要通过自定义子类重写 Header 方法实现自定义页眉 Logo：

// 自定义TCPDF子类重写Header方法
class CustomTCPDF extends TCPDF {
    // 重写页眉逻辑
    public function Header() {
        /* Image方法参数说明：
        1. Logo文件*绝对路径* 2. 左上角X坐标 3. 左上角Y坐标 4. 宽度 5. 高度
        6. 文件类型 7. 跳转链接 8. 对齐方式 9. 插值开关 10. 分辨率 11. 边框开关
        */
        $this->Image('/www/server/your_project/static/logo.png', 15, 5, 30, '', 'PNG', '', 'T', false, 300, '', false, false, 0, false, false, false);
        // 可在页眉追加文字
        $this->SetFont('stsongstdlight', '', 14);
        $this->Cell(0, 15, '员工工资单', 0, false, 'R', 0, '', 0, false, 'M', 'M');
    }
}
// 实例化时使用自定义类即可自动生效自定义页眉
$pdf = new CustomTCPDF(PDF_PAGE_ORIENTATION, PDF_UNIT, PDF_PAGE_FORMAT, true, 'UTF-8', false);

注意必须传入绝对文件路径，不要使用相对路径，TCPDF 对相对路径兼容性极差；如果是远程图片需要先下载到本地临时目录再传入路径。

2. tr/td 等HTML元素无法正常渲染的解决 #

TCPDF 的 writeHTML 方法对 HTML 语法要求非常严格，满足以下规则即可正常渲染表格：

• 所有标签必须完整闭合，包括 <tr></tr> <td></td>，不能存在未闭合标签
• 表格必须包含完整结构，外层必须套 <table>，表头建议套 <thead>、内容套 <tbody>
• 仅支持内联样式，仅兼容基础样式属性：width/height/border/background-color/color/font-size/text-align，不支持外部 CSS、类选择器
• 不要在 td 内嵌套多层复杂块级元素

正确示例代码：

$html = '
<table border="1" cellpadding="5" cellspacing="0" width="100%">
    <thead>
        <tr style="background-color:#f0f0f0;">
            <td width="20%" style="text-align:center;">员工姓名</td>
            <td width="25%" style="text-align:center;">岗位</td>
            <td width="25%" style="text-align:center;">应发工资</td>
            <td width="30%" style="text-align:center;">实发工资</td>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td style="text-align:center;">张三</td>
            <td style="text-align:center;">技术部</td>
            <td style="text-align:center;">12000</td>
            <td style="text-align:center;">9800</td>
        </tr>
    </tbody>
</table>';
// 输出HTML时第二个参数设为true，允许渲染表格边框
$pdf->writeHTML($html, true, false, true, false, '');

如果仍渲染失败，可先把拼接好的 HTML 字符串输出到浏览器，排查是否存在标签漏闭合、引号不配对等语法问题。

3. img 标签插入 Logo 不生效的解决 #

TCPDF 对 HTML 中 img 标签的支持有特殊要求：

• 必须使用绝对路径，不能用相对路径或者 Web 路径，需要传入服务器本地绝对路径，例如拼接 $_SERVER['DOCUMENT_ROOT'] 补全路径
• 必须显式指定 width 和 height 属性，不能省略
• 不支持 webp、svg 等特殊格式，优先使用 png、jpg 格式

正确示例代码：

// 先拼接服务器本地绝对路径
$logo_path = $_SERVER['DOCUMENT_ROOT'].'/static/logo.png';
$html = '<div style="text-align:center;">
    <img src="'.$logo_path.'" width="120" height="40" alt="公司Logo">
    <h2>2024年6月员工工资单</h2>
</div>';
$pdf->writeHTML($html, true, false, true, false, '');

如果仍不生效，建议直接调用 TCPDF 原生的 Image() 方法插入图片，兼容性远高于 HTML 的 img 标签。

样式自定义通用注意事项 #

• 中文字体需要提前导入，不要使用系统默认字体避免乱码，可通过 SetFont('stsongstdlight', '', 12) 调用内置宋体
• 提前通过 SetMargins()、SetAutoPageBreak() 设置页面边距、自动分页规则，避免内容超出页面
• 复杂格式优先使用 TCPDF 原生的 Cell、MultiCell 方法实现，比 HTML 渲染的兼容性更高

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