圖片

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 渲染功能