值对象

TCPDF-Next 对所有几何与色彩数据使用不可变值对象。每个值对象皆声明为 final readonly — 一旦创建就无法修改。需要变更时，请创建新的实例。

PageSize

表示页面尺寸，单位为点（1 pt = 1/72 英寸）。

use Yeeefang\TcpdfNext\ValueObjects\PageSize;

// ISO 216 A 系列
$a4 = PageSize::A4();             // 595.28 x 841.89 pt

// 方向切换（返回新实例）
$landscape = PageSize::A4()->landscape();   // 841.89 x 595.28 pt
$portrait = PageSize::A4()->portrait();     // 595.28 x 841.89 pt

// 从名称字符串创建
$letter = PageSize::fromName('Letter');

// 自定义尺寸（单位为点）
$custom = new PageSize(400.0, 600.0, 'custom');

工厂方法

系列	方法
ISO A	A0(), A1(), A2(), A3(), A4(), A5(), A6()
ISO B	B0(), B1(), B2(), B3(), B4(), B5()
北美	Letter(), Legal(), Tabloid()

Margin

定义页面边界，单位为毫米。

use Yeeefang\TcpdfNext\ValueObjects\Margin;

// 四边相同
$uniform = Margin::uniform(10.0);               // 四边皆 10mm

// 对称：垂直与水平
$symmetric = Margin::symmetric(15.0, 10.0);     // 上下 15mm、左右 10mm

// 无边界
$zero = Margin::zero();

// 明确指定：上、右、下、左
$explicit = new Margin(20.0, 15.0, 25.0, 15.0);

通过公开只读属性访问各边值：$margin->top、$margin->right、$margin->bottom、$margin->left。

Position 与 Dimension

简洁的坐标与尺寸配对，提供公开只读属性。

use Yeeefang\TcpdfNext\ValueObjects\{Position, Dimension};

$pos = new Position(50.0, 100.0);   // $pos->x, $pos->y
$dim = new Dimension(210.0, 297.0); // $dim->width, $dim->height

Position 代表文件中的一个 (x, y) 坐标点，Dimension 代表一个宽高尺寸。两者皆为 final readonly，适合在不同页面或方法间安全传递。

Unit

处理单位定义与点、毫米、厘米、英寸之间的转换。

use Yeeefang\TcpdfNext\ValueObjects\Unit;

$mm = Unit::mm();  // 另有：Unit::pt(), Unit::cm(), Unit::in()

// 单位转换
$points = Unit::convert(25.4, Unit::mm(), Unit::pt());   // 25.4mm = 72pt
$inches = Unit::convert(72.0, Unit::pt(), Unit::in());   // 72pt = 1in

转换参考

来源	等于多少点
1 pt	1.0
1 mm	2.8346
1 cm	28.3465
1 in	72.0

Color

Color 类位于 Graphics 命名空间，支持 RGB、CMYK、灰度与专色模型。如同所有值对象，它是不可变的。

use Yeeefang\TcpdfNext\Graphics\Color;

// RGB (0-255)
$red = Color::rgb(255, 0, 0);
$orange = Color::rgb(255, 102, 0);

// CMYK (0-100)
$processBlack = Color::cmyk(0, 0, 0, 100);
$cyan = Color::cmyk(100, 0, 0, 0);

// 灰度 (0-255，0 = 黑色，255 = 白色)
$gray = Color::gray(128);

// 专色（名称 + CMYK 备选）
$pantone = Color::spot('Pantone 151 C', 0, 60, 100, 0);

RGB 适用于屏幕显示场景，CMYK 适用于专业印刷需求，专色则用于品牌色彩需要精确再现的情况。

综合范例

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\ValueObjects\{PageSize, Margin, Unit};
use Yeeefang\TcpdfNext\Graphics\Color;

$landscape = PageSize::A4()->landscape();
$margins = Margin::symmetric(15.0, 10.0);
$orange = Color::rgb(255, 102, 0);

$pdf = Document::create()
    ->addPage($landscape, margin: $margins)
    ->setFont('Helvetica', '', 12)
    ->setTextColor($orange)
    ->cell(0, 10, '使用值对象设置样式')
    ->save('styled.pdf');

所有值对象皆为 final readonly。landscape() 和 portrait() 等方法返回新实例 — 永远不会修改原始对象。这让值对象可以安全地在页面、线程与函数边界间共用，无需防御性复制。