值对象 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）
• 接口参考 — 接口方法中引用的值对象类型