圖片

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 擴充套件支援對應格式。