色彩

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）。