值物件 API

值物件是 TCPDF-Next 中表達尺寸、位置、色彩等概念的不可變型別。所有值物件建立後即不可修改，任何「修改」操作都會回傳新的實例。

命名空間：TcpdfNext\ValueObjects

---

PageSize

表示頁面尺寸，提供預定義常數與自訂尺寸工廠方法。

預定義常數

常數	尺寸（mm）	說明
PageSize::A3	297 x 420	ISO A3
PageSize::A4	210 x 297	ISO A4
PageSize::A5	148 x 210	ISO A5
PageSize::A6	105 x 148	ISO A6
PageSize::B4	250 x 353	ISO B4
PageSize::B5	176 x 250	ISO B5
PageSize::Letter	215.9 x 279.4	美規 Letter (8.5 x 11 in)
PageSize::Legal	215.9 x 355.6	美規 Legal (8.5 x 14 in)
PageSize::Tabloid	279.4 x 431.8	美規 Tabloid (11 x 17 in)

工廠方法

// 自訂尺寸（毫米）
public static function custom(float $width, float $height): self

// 從英吋建立
public static function fromInches(float $width, float $height): self

// 從點數建立（1 pt = 1/72 in）
public static function fromPoints(float $width, float $height): self

實例方法

// 取得 Dimension 值物件
public function dimension(): Dimension

// 取得橫向版本（寬高互換，保證寬 > 高）
public function landscape(): self

// 取得直向版本（保證高 > 寬）
public function portrait(): self

使用範例

use TcpdfNext\ValueObjects\PageSize;

$a4 = PageSize::A4;
echo $a4->dimension()->width;  // 210.0

$custom = PageSize::custom(width: 200, height: 300);
$landscape = $custom->landscape();
echo $landscape->dimension()->width;  // 300.0

---

Margin

表示頁面的四邊邊距（毫米）。

工廠方法

// 四邊獨立設定
public static function create(float $top, float $right, float $bottom, float $left): self

// 對稱設定（水平用於左右，垂直用於上下）
public static function symmetric(float $horizontal, float $vertical): self

// 四邊統一值
public static function all(float $value): self

// 無邊距
public static function zero(): self

唯讀屬性

public readonly float $top;
public readonly float $right;
public readonly float $bottom;
public readonly float $left;

實例方法

// 回傳修改單邊的新實例
public function withTop(float $value): self
public function withRight(float $value): self
public function withBottom(float $value): self
public function withLeft(float $value): self

// 等比縮放（回傳新實例）
public function scale(float $factor): self

使用範例

use TcpdfNext\ValueObjects\Margin;

$margin = Margin::symmetric(horizontal: 20, vertical: 25);
echo $margin->top;    // 25.0
echo $margin->left;   // 20.0

$wider = $margin->withLeft(30)->withRight(30);
echo $wider->left;    // 30.0
echo $wider->top;     // 25.0（未變）

---

Position

表示二維座標點（毫米）。

工廠方法

// 建立座標
public static function create(float $x, float $y): self

// 原點 (0, 0)
public static function origin(): self

唯讀屬性

public readonly float $x;
public readonly float $y;

實例方法

// 單位轉換
public function xInPoints(): float    // mm -> pt
public function yInPoints(): float

// 偏移（回傳新實例）
public function offset(float $dx, float $dy): self

使用範例

use TcpdfNext\ValueObjects\Position;

$pos = Position::create(x: 10, y: 20);
$moved = $pos->offset(dx: 5, dy: -3);
echo $moved->x;  // 15.0
echo $moved->y;  // 17.0

echo $pos->xInPoints();  // 28.35

---

Dimension

表示二維尺寸（寬度與高度，毫米）。

工廠方法

public static function create(float $width, float $height): self

唯讀屬性

public readonly float $width;
public readonly float $height;

實例方法

// 單位轉換（1 mm = 2.8346 pt）
public function widthInPoints(): float
public function heightInPoints(): float

// 寬高互換（回傳新實例）
public function swap(): self

// 等比縮放（回傳新實例）
public function scale(float $factor): self

使用範例

use TcpdfNext\ValueObjects\Dimension;

$dim = Dimension::create(width: 210, height: 297);
echo $dim->widthInPoints();   // 595.28

$half = $dim->scale(factor: 0.5);
echo $half->width;   // 105.0
echo $half->height;  // 148.5

$swapped = $dim->swap();
echo $swapped->width;  // 297.0

---

Unit

度量單位轉換工具。提供毫米、點、英吋、公分之間的轉換。

靜態轉換方法

// 毫米 <-> 點
public static function mmToPoints(float $mm): float
public static function pointsToMm(float $pt): float

// 毫米 <-> 英吋
public static function mmToInches(float $mm): float
public static function inchesToMm(float $inches): float

// 毫米 <-> 公分
public static function mmToCm(float $mm): float
public static function cmToMm(float $cm): float

// 點 <-> 英吋
public static function pointsToInches(float $pt): float
public static function inchesToPoints(float $inches): float

轉換常數

public const POINTS_PER_MM   = 2.834645669;  // 1 mm = 2.8346 pt
public const MM_PER_INCH     = 25.4;         // 1 in = 25.4 mm
public const POINTS_PER_INCH = 72.0;         // 1 in = 72 pt

使用範例

use TcpdfNext\ValueObjects\Unit;

echo Unit::mmToPoints(210);      // 595.28
echo Unit::inchesToMm(8.5);     // 215.9
echo Unit::pointsToMm(595.28);  // 210.0

---

Color

表示色彩值，支援 RGB、CMYK、灰階與十六進位格式。

工廠方法

// RGB（各通道 0-255）
public static function rgb(int $r, int $g, int $b): self

// 十六進位（#RRGGBB 或 #RGB）
public static function hex(string $hex): self

// CMYK（各通道 0-100）
public static function cmyk(int $c, int $m, int $y, int $k): self

// 灰階（0-100，0 = 黑色，100 = 白色）
public static function gray(int $value): self

// 預定義色彩
public static function black(): self
public static function white(): self

實例方法

// 取得色彩空間
public function getColorSpace(): ColorSpace

// RGB 通道（0-255）
public function getRed(): int
public function getGreen(): int
public function getBlue(): int

// CMYK 通道（0-100）
public function getCyan(): int
public function getMagenta(): int
public function getYellow(): int
public function getBlack(): int

// 轉換為十六進位字串
public function toHex(): string              // 例如 '#FF0000'

// 轉換為 PDF 色彩運算子參數
public function toPdfOperands(): string

使用範例

use TcpdfNext\ValueObjects\Color;

$red = Color::rgb(r: 255, g: 0, b: 0);
echo $red->toHex();          // '#FF0000'
echo $red->getColorSpace();  // ColorSpace::DeviceRGB

$brand = Color::hex('#003366');
echo $brand->getRed();    // 0
echo $brand->getGreen();  // 51
echo $brand->getBlue();   // 102

$printCyan = Color::cmyk(c: 100, m: 0, y: 0, k: 0);
$halfGray  = Color::gray(50);

---

設計原則

所有值物件遵循以下設計原則：

原則	說明
不可變性	所有屬性皆為 readonly。修改方法回傳新實例，原實例不受影響。
自我驗證	建構時即檢查數值合法性。例如 RGB 通道超出 0-255 會拋出 \InvalidArgumentException。
型別安全	使用強型別取代原始數值。避免將寬度誤傳為高度等參數混淆。
值語意	兩個屬性值完全相同的值物件視為相等（值相等，非參考相等）。

---

相關頁面

• Document API — 使用值物件作為方法參數
• 列舉參考 — 與值物件搭配的列舉型別（ColorSpace、Orientation）
• 介面參考 — 介面方法中引用的值物件型別