颜色

TCPDF-Next 通过 HasColors trait、Graphics\Color 值对象及 Graphics\ColorSpace 抽象层提供完整的颜色管理功能。颜色可以分别应用于描边、填充与文字。

基本颜色设置

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setDrawColor(255, 0, 0)      // 红色描边
    ->setFillColor(0, 0, 255)      // 蓝色填充
    ->setTextColor(51, 51, 51);    // 深灰色文字

方法签名

setDrawColor(int $r, int $g = -1, int $b = -1): static   // 描边颜色
setFillColor(int $r, int $g = -1, int $b = -1): static   // 填充颜色
setTextColor(int $r, int $g = -1, int $b = -1): static   // 文字颜色

当只提供 $r 参数时（$g 与 $b 默认为 -1），该值会被视为灰阶（0 = 黑色，255 = 白色）。

Color 值对象

use Yeeefang\TcpdfNext\Graphics\Color;

$red  = Color::rgb(255, 0, 0);
$cyan = Color::cmyk(100, 0, 0, 0);
$gray = Color::gray(128);
$spot = Color::spot('Pantone 151 C', 0, 60, 100, 0);

工厂方法	参数	颜色空间
Color::rgb(r, g, b)	每个通道 0--255	DeviceRGB
Color::cmyk(c, m, y, k)	每个通道 0--100	DeviceCMYK
Color::gray(value)	0--255	DeviceGray
Color::spot(name, c, m, y, k)	名称 + CMYK 后备值	Separation

颜色空间

颜色空间	使用场景
DeviceRGB	屏幕导向的输出（网页、演示文稿）
DeviceCMYK	印刷导向的输出（商业印刷）
DeviceGray	灰阶文档
Separation	特别色 / Pantone 色，用于品牌颜色的精准重现

CMYK 数值会直接写入 PDF 流。如需颜色管理流程，可通过 setColorProfile() 嵌入 ICC 配置文件。

透明度

setAlpha(float $opacity = 1.0, string $blendMode = 'Normal'): static

$pdf->setAlpha(0.5, 'Multiply')    // 50% 不透明度 + Multiply 混合
    ->rect(10, 10, 50, 30, 'F')
    ->setAlpha(1.0);                // 重置为完全不透明

在透明区段结束后，务必将不透明度重置为 1.0，以避免对后续内容产生非预期的效果。

混合模式

TCPDF-Next 支持 PDF 规范中全部 16 种混合模式：

模式	效果
Normal	来源覆盖目标（默认）
Multiply	加深 — 通道值相乘
Screen	变亮 — 反向相乘
Overlay	结合 Multiply 与 Screen
Darken / Lighten	逐通道取较暗 / 较亮的值
ColorDodge / ColorBurn	加亮 / 加深目标
HardLight / SoftLight	强烈 / 柔和的光线效果
Difference / Exclusion	通道差值（高 / 低对比）
Hue / Saturation	取来源的色相或饱和度，保留目标的亮度
Color / Luminosity	取来源的颜色或亮度

渐变

四种渐变类型会以原生 PDF 着色对象（shading object）渲染：

$pdf->linearGradient(10, 10, 100, 50, '#ff0000', '#0000ff', [0, 0, 1, 1]);   // 线性渐变
$pdf->radialGradient(60, 60, 80, 80, '#ffffff', '#000000');                    // 径向渐变
$pdf->coonsPatchMesh(10, 10, 100, 100, $colors, $coords);       // Coons patch mesh
$pdf->tensorProductPatchMesh(10, 10, 100, 100, $colors, $coords); // Tensor-product

• 线性渐变 — 沿着方向向量的双色渐变。
• 径向渐变 — 从中心点向外扩展的双色渐变。
• Coons patch mesh — 通过贝塞尔控制点定义的复杂多色填充。
• Tensor-product patch mesh — Coons 的扩展版本，增加了内部控制点。

完整示例

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setDrawColor(255, 0, 0)       // 红色描边
    ->setFillColor(0, 0, 255)       // 蓝色填充
    ->rect(10, 10, 50, 30, 'DF')    // 描边 + 填充
    ->setAlpha(0.5, 'Multiply')     // 50% 不透明度 + Multiply 混合模式
    ->setFillColor(255, 255, 0)     // 黄色
    ->rect(30, 20, 50, 30, 'F')     // 半透明矩形叠加
    ->setAlpha(1.0);                // 重置不透明度

实用提示

• 屏幕显示的 PDF 使用 DeviceRGB，商业印刷用 DeviceCMYK。
• 特别色需要 SpotColorManager — 它会在首次使用时惰性初始化。
• 透明区段结束后，务必将 alpha 重置为 1.0。
• 渐变坐标使用当前的用户单位系统（默认：mm）。