API Value Object
Mọi value object trong TCPDF-Next đều bất biến. Mọi method "modifier" trả về instance mới, giữ nguyên bản gốc. Điều này loại bỏ một loại lỗi do shared mutable state.
PageSize
Namespace: TcpdfNext\ValueObjects\PageSize
Biểu diễn kích thước trang. Nội bộ mọi phép đo được lưu bằng PDF point (1/72 inch).
Factory Method (ISO A Series)
PageSize::a0(): static
841 x 1189 mm
PageSize::a1(): static
594 x 841 mm
PageSize::a2(): static
420 x 594 mm
PageSize::a3(): static
297 x 420 mm
PageSize::a4(): static
210 x 297 mm (mặc định)
PageSize::a5(): static
148 x 210 mm
PageSize::a6(): static
105 x 148 mm
Factory Method (ISO B Series)
PageSize::b0(): static
1000 x 1414 mm
PageSize::b1(): static
707 x 1000 mm
PageSize::b2(): static
500 x 707 mm
PageSize::b3(): static
353 x 500 mm
PageSize::b4(): static
250 x 353 mm
PageSize::b5(): static
176 x 250 mm
Factory Method (Bắc Mỹ)
PageSize::letter(): static
8.5 x 11 in (215.9 x 279.4 mm)
PageSize::legal(): static
8.5 x 14 in (215.9 x 355.6 mm)
PageSize::tabloid(): static
11 x 17 in (279.4 x 431.8 mm)
Tùy chỉnh & Tra cứu
PageSize::fromMm(float $width, float $height, string $name = 'Custom'): static
Tạo kích thước trang từ đơn vị millimeter.
PageSize::fromPoints(float $width, float $height, string $name = 'Custom'): static
Tạo kích thước trang từ đơn vị point.
PageSize::fromName(string $name): static
Tra cứu kích thước trang chuẩn theo tên (không phân biệt hoa thường). Throw InvalidArgumentException cho tên không biết.
Helper hướng trang
landscape(): static
Trả về PageSize mới với chiều rộng và chiều cao hoán đổi sao cho rộng > cao.
portrait(): static
Trả về PageSize mới với chiều rộng và chiều cao hoán đổi sao cho cao > rộng.
Thuộc tính
| Thuộc tính | Kiểu | Mô tả |
|---|---|---|
$width | float | Chiều rộng tính bằng point |
$height | float | Chiều cao tính bằng point |
$name | string | Tên dễ đọc (vd: 'A4', 'Letter') |
Method tiện lợi
widthMm(): float
Trả về chiều rộng tính bằng millimeter.
heightMm(): float
Trả về chiều cao tính bằng millimeter.
Ví dụ
php
use TcpdfNext\ValueObjects\PageSize;
$a4 = PageSize::a4();
$landscape = $a4->landscape(); // 297 x 210 mm
$custom = PageSize::fromMm(140, 216, 'Half Letter');
$letter = PageSize::fromName('Letter');Margin
Namespace: TcpdfNext\ValueObjects\Margin
Biểu diễn margin trang bốn cạnh. Lưu trữ nội bộ bằng PDF point.
Factory Method
Margin::mm(float $top, float $right, float $bottom, float $left): static
Tạo margin từ giá trị millimeter.
Margin::pt(float $top, float $right, float $bottom, float $left): static
Tạo margin từ giá trị point.
Margin::uniform(float $value): static
Bốn cạnh bằng nhau (tính bằng point).
Margin::uniformMm(float $value): static
Bốn cạnh bằng nhau (tính bằng millimeter).
Margin::symmetric(float $horizontal, float $vertical): static
Margin đối xứng (horizontal = trái + phải, vertical = trên + dưới) tính bằng point.
Margin::zero(): static
Mọi margin về không.
Thuộc tính
| Thuộc tính | Kiểu | Mô tả |
|---|---|---|
$top | float | Margin trên tính bằng point |
$right | float | Margin phải tính bằng point |
$bottom | float | Margin dưới tính bằng point |
$left | float | Margin trái tính bằng point |
Method Modifier
withTop(float $value): static
Trả về Margin mới với giá trị top thay thế (tính bằng point).
withRight(float $value): static
Trả về Margin mới với giá trị right thay thế.
withBottom(float $value): static
Trả về Margin mới với giá trị bottom thay thế.
withLeft(float $value): static
Trả về Margin mới với giá trị left thay thế.
Method tính toán
printableArea(PageSize $pageSize): Dimension
Trả về Dimension vùng in được (kích thước trang trừ margin).
Ví dụ
php
use TcpdfNext\ValueObjects\Margin;
use TcpdfNext\ValueObjects\PageSize;
$margin = Margin::mm(top: 15, right: 20, bottom: 15, left: 20);
$narrow = $margin->withLeft(36.0)->withRight(36.0);
$area = $margin->printableArea(PageSize::a4());
echo $area->widthMm(); // 170.0Position
Namespace: TcpdfNext\ValueObjects\Position
Cặp tọa độ x--y bất biến tính bằng PDF point.
Factory Method
new Position(float $x, float $y)
Tạo từ giá trị point.
Position::mm(float $x, float $y): static
Tạo từ giá trị millimeter (chuyển sang point nội bộ).
Thuộc tính
| Thuộc tính | Kiểu | Mô tả |
|---|---|---|
$x | float | Tọa độ ngang tính bằng point |
$y | float | Tọa độ dọc tính bằng point |
Method
translate(float $dx, float $dy): static
Trả về Position mới dịch chuyển theo (dx, dy) point.
xMm(): float
Trả về x tính bằng millimeter.
yMm(): float
Trả về y tính bằng millimeter.
Ví dụ
php
use TcpdfNext\ValueObjects\Position;
$pos = Position::mm(x: 25.4, y: 50.8);
$shifted = $pos->translate(dx: 10, dy: 20);
echo $shifted->xMm(); // ~28.9Dimension
Namespace: TcpdfNext\ValueObjects\Dimension
Cặp chiều rộng--chiều cao bất biến tính bằng PDF point.
Factory Method
new Dimension(float $width, float $height)
Tạo từ giá trị point.
Dimension::mm(float $width, float $height): static
Tạo từ giá trị millimeter.
Thuộc tính
| Thuộc tính | Kiểu | Mô tả |
|---|---|---|
$width | float | Chiều rộng tính bằng point |
$height | float | Chiều cao tính bằng point |
Method
swap(): static
Trả về Dimension mới với chiều rộng và chiều cao hoán đổi.
widthMm(): float
Trả về chiều rộng tính bằng millimeter.
heightMm(): float
Trả về chiều cao tính bằng millimeter.
area(): float
Trả về diện tích tính bằng point vuông.
Ví dụ
php
use TcpdfNext\ValueObjects\Dimension;
$dim = Dimension::mm(width: 210, height: 297);
echo $dim->width; // 595.28
echo $dim->widthMm(); // 210.0
$swapped = $dim->swap(); // Tương đương 297 x 210 mmUnit
Namespace: TcpdfNext\ValueObjects\Unit
Class tiện ích static để chuyển đổi giữa đơn vị đo. Mọi chuyển đổi dựa trên chuẩn PDF 72 point mỗi inch.
Method chuyển đổi
Unit::mm(float $value): float
Chuyển millimeter sang point. Alias cho mmToPoints().
Unit::pt(float $value): float
Đồng nhất — trả về giá trị không đổi (cho nhất quán API).
Unit::cm(float $value): float
Chuyển centimeter sang point.
Unit::in(float $value): float
Chuyển inch sang point (giá trị x 72).
Unit::mmToPoints(float $mm): float
Chuyển millimeter sang point (mm x 72 / 25.4).
Unit::pointsToMm(float $pt): float
Chuyển point sang millimeter (pt x 25.4 / 72).
Unit::inchesToPoints(float $inches): float
Chuyển inch sang point (inches x 72).
Unit::pointsToInches(float $pt): float
Chuyển point sang inch (pt / 72).
Unit::cmToPoints(float $cm): float
Chuyển centimeter sang point (cm x 72 / 2.54).
Unit::pointsToCm(float $pt): float
Chuyển point sang centimeter (pt x 2.54 / 72).
Unit::convert(float $value, string $from, string $to): float
Bộ chuyển đa năng. Chuỗi đơn vị hỗ trợ: 'mm', 'cm', 'in', 'pt'.
Ví dụ
php
use TcpdfNext\ValueObjects\Unit;
$points = Unit::mmToPoints(210.0); // 595.28
$mm = Unit::pointsToMm(595.28); // 210.0
$points = Unit::inchesToPoints(8.5); // 612.0
$result = Unit::convert(1.0, 'in', 'mm'); // 25.4Color
Namespace: TcpdfNext\Graphics\Color
Biểu diễn màu bất biến hỗ trợ nhiều không gian màu. Mặc dù Color nằm trong package Graphics, nó được dùng rộng rãi xuyên suốt thư viện (màu text, màu vẽ, màu tô, màu bookmark, màu annotation).
Factory Method
Color::rgb(int $r, int $g, int $b): static
Tạo màu DeviceRGB. Giá trị từ 0 đến 255.
Color::cmyk(float $c, float $m, float $y, float $k): static
Tạo màu DeviceCMYK. Giá trị từ 0 đến 100.
Color::gray(int $level): static
Tạo màu DeviceGray. Level từ 0 (đen) đến 255 (trắng).
Color::spot(string $name, Color $fallback, float $tint = 100): static
Tạo named spot color (Separation) với fallback process-color và phần trăm tint.
Color::hex(string $hex): static
Tạo màu từ chuỗi hex 3 hoặc 6 chữ số (có hoặc không có '#').
Color::black(): static
Tiện lợi: rgb(0, 0, 0).
Color::white(): static
Tiện lợi: rgb(255, 255, 255).
Color::transparent(): static
Tiện lợi: màu trong suốt hoàn toàn.
Thuộc tính
| Thuộc tính | Kiểu | Mô tả |
|---|---|---|
$space | ColorSpace | Enum không gian màu (DeviceRGB, DeviceCMYK, DeviceGray, Separation) |
Method
toRgbArray(): array
Trả về [r, g, b] với giá trị 0--255. Chuyển từ CMYK hoặc Gray nếu cần.
toCmykArray(): array
Trả về [c, m, y, k] với giá trị 0--100.
toHex(): string
Trả về chuỗi hex 6 chữ số (vd: 'ff6600').
withAlpha(float $alpha): static
Trả về Color mới với alpha cho trước (0.0--1.0).
equals(Color $other): bool
So sánh hai màu theo giá trị.
Ví dụ
php
use TcpdfNext\Graphics\Color;
$brand = Color::hex('#0066CC');
$print = Color::cmyk(100, 0, 0, 0);
$spot = Color::spot('PANTONE 286 C', Color::cmyk(100, 66, 0, 2));
$faded = $brand->withAlpha(0.5);
echo $brand->toHex(); // '0066cc'Xem thêm
- Tổng quan API -- Mọi package một cái nhìn
- Document API -- Method nhận các value object này
- Tham chiếu Enum -- ColorSpace, Orientation và enum liên quan khác
- Hướng dẫn Value Object -- Tổng quan khái niệm và pattern nâng cao