图片

TCPDF-Next 支持在 PDF 中嵌入多种格式的图片。本示例说明如何从文件路径、URL 或二进制数据插入图片，以及如何控制定位与尺寸。

支持格式

格式	扩展名	透明度	适用场景
JPEG	.jpg, .jpeg	不支持	照片、摄影作品
PNG	.png	Alpha 通道	截图、图标、需要透明背景的图片
SVG	.svg	支持	矢量图形、Logo、图表（缩放不失真）

从文件路径插入

<?php

use YeeeFang\TcpdfNext\Document\PdfDocument;
use YeeeFang\TcpdfNext\Document\PageFormat;

$pdf = PdfDocument::create()
    ->setTitle('图片示例')
    ->setPageFormat(PageFormat::A4)
    ->build();

$page = $pdf->addPage();

// 指定位置与宽度，高度自动按比例计算
$page->addImage('/path/to/logo.png')
    ->setPosition(20, 25)
    ->setSize(50);

// 同时指定宽度与高度
$page->addImage('/path/to/photo.jpg')
    ->setPosition(20, 80)
    ->setSize(80, 60);

从 URL 插入

// 从网络加载图片
$page->addImage('https://example.com/images/product.jpg')
    ->setPosition(20, 25)
    ->setSize(60);

从二进制数据插入

// 从文件内容（二进制字符串）插入
$imageData = file_get_contents('/path/to/image.png');

$page->addImageFromString($imageData, type: 'PNG')
    ->setPosition(20, 25)
    ->setSize(50);

// 从 Base64 字符串插入
$base64 = base64_encode($imageData);

$page->addImageFromBase64($base64, type: 'PNG')
    ->setPosition(20, 80)
    ->setSize(50);

居中图片

// 计算水平居中的 X 坐标
$imageWidth = 80;
$pageWidth = $pdf->getPageWidth();
$margins = $pdf->getMargins();
$contentWidth = $pageWidth - $margins['left'] - $margins['right'];
$x = $margins['left'] + ($contentWidth - $imageWidth) / 2;

$page->addImage('/path/to/centered.jpg')
    ->setPosition($x, 50)
    ->setSize($imageWidth);

SVG 矢量图形

SVG 是矢量格式，无论放大缩小都不会产生锯齿，非常适合 Logo 与图表：

// 从文件插入 SVG
$page->addImage('/path/to/diagram.svg')
    ->setPosition(20, 25)
    ->setSize(100, 80);

// 从 SVG 字符串插入
$svgString = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
    <circle cx="50" cy="50" r="40" fill="#3498DB" />
    <text x="50" y="55" text-anchor="middle" fill="white" font-size="14">PDF</text>
</svg>';

$page->addImageFromString($svgString, type: 'SVG')
    ->setPosition(20, 120)
    ->setSize(50, 50);

图片透明度

// 设置图片的透明度（0.0 完全透明 ~ 1.0 完全不透明）
$page->addImage('/path/to/watermark.png')
    ->setPosition(50, 100)
    ->setSize(100)
    ->setOpacity(0.3);

在 HTML 中使用图片

搭配 HtmlRenderer，也可以用 HTML <img> 标签嵌入图片：

use YeeeFang\TcpdfNext\Html\HtmlRenderer;

$renderer = new HtmlRenderer($pdf);

$html = <<<'HTML'
<div style="text-align: center;">
    <img src="/path/to/photo.jpg" width="200" alt="产品照片" />
    <p style="font-size: 10px; color: #888888;">图一：产品外观</p>
</div>
HTML;

$renderer->writeHtml($html);

注意事项

• 大量高分辨率图片会导致 PDF 文件过大，建议预先压缩图片再嵌入
• 从 URL 加载图片时需注意网络延迟与超时设置
• SVG 中若有外部引用（字体、图片），需确保路径可被访问

下一步

• 多页文件 -- 多页排版与自动分页
• 水印 -- 使用图片作为水印
• HTML 转 PDF -- 更多 HTML 渲染功能