Hình ảnh

TCPDF-Next hỗ trợ nhúng hình ảnh raster và vector vào tài liệu PDF. Hệ thống con hình ảnh nằm trong module Graphics và được truy cập qua fluent API của Document.

Định dạng hỗ trợ

Định dạng	Extension	Alpha	Ghi chú
JPEG	.jpg, .jpeg	Không	Baseline và progressive
PNG	.png	Có	8-bit, 24-bit, 32-bit với transparency
WebP	.webp	Có	Lossy và lossless
AVIF	.avif	Có	Cần GD hoặc Imagick hỗ trợ AVIF
SVG	.svg	--	Vector — render qua SvgParser
EPS	.eps, .ai	--	PostScript — render qua EpsParser

image()

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->image('/path/to/logo.png', 10, 10, 50, 0);   // Rộng=50mm, cao tự động

Signature

image(
    string $file,             // Đường dẫn file, URL hoặc @base64
    float  $x     = '',       // Vị trí X ('' = X hiện tại)
    float  $y     = '',       // Vị trí Y ('' = Y hiện tại)
    float  $w     = 0,        // Chiều rộng (0 = tự động từ tỷ lệ)
    float  $h     = 0,        // Chiều cao (0 = tự động từ tỷ lệ)
    string $type  = '',       // Buộc định dạng: 'JPEG', 'PNG', 'WebP', v.v.
    mixed  $link  = '',       // URL hoặc link identifier nội bộ
    string $align = '',       // Căn chỉnh sau hình ảnh: T, M, B, N
    bool   $resize    = false,
    int    $dpi       = 300,
    string $palign    = '',   // Căn chỉnh hình ảnh trong cell: L, C, R
    bool   $fitbox    = false,
    bool   $fitonpage = false
): static

Định vị và Scale

$pdf->image('/path/to/photo.jpg', 10, 60, 100, 80);      // Tuyệt đối: 100x80mm tại (10,60)
$pdf->image('/path/to/banner.png', 10, 10, 190, 0);       // Cao tự động từ rộng
$pdf->image('/path/to/portrait.jpg', 10, 10, 0, 100);     // Rộng tự động từ cao
$pdf->image('/path/to/photo.jpg', 10, 10, 80, 60, fitbox: true);    // Vừa trong hộp
$pdf->image('/path/to/chart.png', 10, 10, 0, 0, fitonpage: true);   // Vừa trên trang

• Vị trí tuyệt đối — cung cấp tọa độ $x, $y rõ ràng (đơn vị mặc định: mm).
• Cao/rộng tự động — đặt một chiều là 0; chiều kia tính từ tỷ lệ khung hình.
• Vừa trong hộp (fitbox: true) — scale vừa $w x $h giữ tỷ lệ.
• Vừa trên trang (fitonpage: true) — đảm bảo hình ảnh không vượt vùng in.

DPI và độ phân giải

Tham số $dpi kiểm soát ánh xạ pixel-sang-kích-thước-vật-lý khi cả $w và $h là 0:

$pdf->image('/path/to/scan.jpg', 10, 10, 0, 0, dpi: 150);  // Lớn hơn trên trang
$pdf->image('/path/to/scan.jpg', 10, 10, 0, 0, dpi: 300);  // Nhỏ hơn trên trang

Hình ảnh từ chuỗi hoặc URL

$pdf->image('https://example.com/logo.png', 10, 10, 50, 0);           // Từ URL
$pdf->image('@' . base64_encode($imageData), 10, 10, 50, 0, 'PNG');   // Từ base64

Khi tải từ chuỗi base64, cung cấp tham số $type để bộ phân tích biết định dạng.

Hình ảnh với link

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

Hình ảnh SVG

imageSvg() render SVG thành path vector PDF native — không rasterize:

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);

Hình ảnh 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);

Ví dụ đầy đủ

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->image('/path/to/logo.png', 10, 10, 50, 0)
    ->image('/path/to/photo.jpg', 10, 60, 100, 80)
    ->imageSvg('/path/to/diagram.svg', 10, 150, 180, 100)
    ->save('output.pdf');

Mẹo

• Kênh alpha PNG được bảo toàn đầy đủ trong PDF output.
• Để có chất lượng in tốt nhất, dùng hình ảnh 300 DPI trở lên.
• Render SVG hỗ trợ hầu hết tính năng tĩnh; animation và JavaScript bị bỏ qua.
• Khi nhúng nhiều hình ảnh, cân nhắc resize trước file lớn để kiểm soát bộ nhớ.