图片

TCPDF-Next 支持在 PDF 文档中嵌入位图与矢量图片。图片子系统位于 Graphics 模块中，通过 Document 的 Fluent API 访问。

支持格式

格式	扩展名	透明度	备注
JPEG	.jpg、.jpeg	不支持	基准型（Baseline）与渐进式（Progressive）
PNG	.png	支持	8 位、24 位、32 位（含透明通道）
WebP	.webp	支持	有损与无损压缩
AVIF	.avif	支持	需要 GD 或 Imagick 支持 AVIF
SVG	.svg	--	矢量图 — 通过 SvgParser 渲染
EPS	.eps、.ai	--	PostScript — 通过 EpsParser 渲染

image()

image() 是最通用的图片嵌入方法，支持所有位图格式：

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->image('/path/to/logo.png', 10, 10, 50, 0);   // 宽度 50mm，高度自动计算

方法签名

image(
    string $file,             // 文件路径、URL 或 @base64 字符串
    float  $x     = '',       // X 坐标（'' = 当前 X 位置）
    float  $y     = '',       // Y 坐标（'' = 当前 Y 位置）
    float  $w     = 0,        // 宽度（0 = 依比例自动计算）
    float  $h     = 0,        // 高度（0 = 依比例自动计算）
    string $type  = '',       // 强制格式：'JPEG'、'PNG'、'WebP' 等
    mixed  $link  = '',       // URL 或内部链接标识码
    string $align = '',       // 图片后的对齐方式：T、M、B、N
    bool   $resize    = false,
    int    $dpi       = 300,
    string $palign    = '',   // 单元格内的图片对齐：L、C、R
    bool   $fitbox    = false,
    bool   $fitonpage = false
): static

定位与缩放

// 绝对定位：100x80mm，位于坐标 (10, 60)
$pdf->image('/path/to/photo.jpg', 10, 60, 100, 80);

// 指定宽度，高度自动计算
$pdf->image('/path/to/banner.png', 10, 10, 190, 0);

// 指定高度，宽度自动计算
$pdf->image('/path/to/portrait.jpg', 10, 10, 0, 100);

// 适应矩形区域（保持原始比例）
$pdf->image('/path/to/photo.jpg', 10, 10, 80, 60, fitbox: true);

// 适应页面（不超出可打印区域）
$pdf->image('/path/to/chart.png', 10, 10, 0, 0, fitonpage: true);

几种常见的定位策略：

• 绝对定位 — 提供明确的 $x、$y 坐标（默认单位：mm）。
• 自动高度/宽度 — 将其中一个维度设为 0，另一个维度会根据原始比例自动计算。
• 适应矩形（fitbox: true）— 在 $w x $h 的范围内等比例缩放。
• 适应页面（fitonpage: true）— 确保图片不超出页面可打印区域。

图片 DPI 与分辨率

$dpi 参数控制像素到物理尺寸的映射。当 $w 和 $h 皆为 0 时，DPI 决定图片在页面上的实际大小：

$pdf->image('/path/to/scan.jpg', 10, 10, 0, 0, dpi: 150);  // 页面上显示较大
$pdf->image('/path/to/scan.jpg', 10, 10, 0, 0, dpi: 300);  // 页面上显示较小

DPI 越高，相同像素的图片在页面上会显示得越小，但打印品质更高。建议用于打印的图片至少使用 300 DPI。

从字符串或 URL 载入

// 从 URL 载入
$pdf->image('https://example.com/logo.png', 10, 10, 50, 0);

// 从 Base64 字符串载入
$pdf->image('@' . base64_encode($imageData), 10, 10, 50, 0, 'PNG');

从 Base64 字符串载入时，请务必提供 $type 参数，让解析器能辨识图片格式。

图片加上链接

$pdf->image('/path/to/logo.png', 10, 10, 40, 0, link: 'https://example.com');

点击图片即可打开指定的 URL，适合用于品牌商标或导航用途。

SVG 图片

imageSvg() 将 SVG 渲染为原生的 PDF 矢量路径，不会进行位图化，输出品质与缩放无关：

imageSvg(
    string $file,
    float  $x,
    float  $y,
    float  $w,
    float  $h,
    mixed  $link   = '',
    string $align  = '',
    string $palign = '',
    mixed  $border = 0
): static

$pdf->imageSvg('/path/to/diagram.svg', 10, 150, 180, 100);

EPS / PostScript 图片

imageEps(
    string $file,
    float  $x,
    float  $y,
    float  $w,
    float  $h,
    mixed  $link     = '',
    bool   $useBBox  = true,
    string $align    = '',
    string $palign   = '',
    mixed  $border   = 0
): static

$pdf->imageEps('/path/to/illustration.eps', 10, 10, 80, 60);

完整示例

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    // 公司商标
    ->image('/path/to/logo.png', 10, 10, 50, 0, link: 'https://example.com')
    // 产品照片
    ->image('/path/to/photo.jpg', 10, 60, 100, 80)
    // 矢量图表
    ->imageSvg('/path/to/diagram.svg', 10, 150, 180, 100)
    ->save('output.pdf');

提示

• PNG 的 Alpha 透明通道会完整保留到 PDF 输出中。
• 为获得最佳打印品质，建议使用 300 DPI 或更高分辨率的图片。
• SVG 渲染支持大部分静态特性；动画与 JavaScript 会被忽略。
• 嵌入大量图片时，建议事先缩小大型文件，以控制内存使用量。
• WebP 和 AVIF 格式需要 PHP 的 GD 或 Imagick 扩展支持对应格式。