跳到內容
NextPDF

繪製漸層並使用透明度與混合模式

重點摘要

標題為「重點摘要」的區段

以兩端點的軸向（線性）或放射狀漸層填滿一塊區域，再用固定 alpha 與指定的混合模式，合成彼此重疊的形狀。範例程式碼依循 examples/25-gradients.php 與 examples/20-transparency.php。

漸層是一種 ISO 32000-2 shading（著色）。linearGradient() 會產生 Type 2（軸向）shading，而 radialGradient() 會產生 Type 3（放射狀）shading。透明度則是圖形狀態中的 alpha 常數。setAlpha() 會設定非描邊的 ca 值與描邊的 CA 值。

安裝

標題為「安裝」的區段
Terminal window
composer require nextpdf/core:^3

不需要任何選用擴充功能。漸層、alpha 與混合模式 API 自 1.0.0 起即為穩定版，並可在 8.1–8.4 的回溯相容矩陣上執行。

概念總覽

標題為「概念總覽」的區段

linearGradient(x, y, w, h, start, end) 會沿著方框的軸線，在兩個 Color 端點之間繪製色彩漸變。ISO 32000-2 將軸向 shading 的 Coords 定義為 [x0 y0 x1 y1]。如果兩個端點重合，則不會繪製任何內容。radialGradient(...) 會在兩個圓之間進行漸變。放射狀的 Coords 為 [x0 y0 r0 x1 y1 r1]，且兩個半徑都必須 ≥ 0。

setAlpha($alpha, $mode) 會為後續繪製設定固定不透明度。第一個引數是 alpha 常數（ca/CA）。第二個引數會選定混合模式（在透明影像模型中即 BM）。繪製不相關的內容之前，請先把 alpha 重設為 1.0，並把混合模式重設為 Normal。

API 介面

標題為「API 介面」的區段

此 API 介面由 PHPDoc 自動產生。本範例會用到下列方法：

  • linearGradient(float $x, float $y, float $w, float $h, Color $start, Color $end): static
  • radialGradient(float $x, float $y, float $w, float $h, Color $start, Color $end): static
  • setAlpha(float $alpha, BlendMode $mode = BlendMode::Normal): static
  • Color::rgb(int $r, int $g, int $b)、Color::white()、Color::black() 提供漸層的色彩端點。
  • setFillColor(...) 會設定供 alpha 與混合模式合成的顏色。

程式碼範例 — 快速上手

標題為「程式碼範例 — 快速上手」的區段
<?php


declare(strict_types=1);


require_once __DIR__ . '/vendor/autoload.php';


use NextPDF\Core\Document;
use NextPDF\Graphics\BlendMode;
use NextPDF\Graphics\Color;


$doc = Document::createStandalone();
$doc->addPage();


// Axial gradient: blue -> white across a 190 x 40 box.
$doc->linearGradient(10, 30, 190, 40, Color::rgb(30, 58, 138), Color::white());


// Two overlapping rectangles at 70% opacity with Multiply blend.
$doc->setAlpha(0.7, BlendMode::Multiply);
$doc->setFillColor(220, 38, 38);
$doc->rect(20, 90, 60, 40, 'F');
$doc->setFillColor(37, 99, 235);
$doc->rect(50, 90, 60, 40, 'F');
$doc->setAlpha(1.0, BlendMode::Normal); // reset


$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/gradients.pdf');

程式碼範例 — 正式環境

標題為「程式碼範例 — 正式環境」的區段

這是完整、可直接用於測試載具的範例。它會遵循 NEXTPDF_COOKBOOK_OUTPUT，且不會自行固定任何熵。

<?php


declare(strict_types=1);


require_once __DIR__ . '/vendor/autoload.php';


use NextPDF\Core\Document;
use NextPDF\Graphics\BlendMode;
use NextPDF\Graphics\Color;


$doc = Document::createStandalone();
$doc->setTitle('Gradients and Transparency');
$doc->addPage();


$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Gradients and Transparency', newLine: true);
$doc->ln(4);


// 1. Axial gradient — blue to white.
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, '1. Axial gradient', newLine: true);
$doc->ln(2);
$doc->linearGradient(
    x: 10, y: $doc->getY(), w: 190, h: 40,
    start: Color::rgb(30, 58, 138), end: Color::white(),
);
$doc->ln(44);


// 2. Radial gradient — red centre fading to white.
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, '2. Radial gradient', newLine: true);
$doc->ln(2);
$doc->radialGradient(
    x: 50, y: $doc->getY(), w: 110, h: 55,
    start: Color::rgb(220, 38, 38), end: Color::white(),
);
$doc->ln(59);


// 3. Constant alpha + blend mode over a light backdrop.
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, '3. Alpha 0.7 with Multiply blend', newLine: true);
$doc->ln(2);
$baseY = $doc->getY();
$doc->setAlpha(1.0, BlendMode::Normal);
$doc->setFillColor(245, 245, 245);
$doc->rect(15, $baseY, 90, 40, 'F');
$doc->setAlpha(0.7, BlendMode::Multiply);
$doc->setFillColor(220, 38, 38);
$doc->rect(20, $baseY + 5, 40, 30, 'F');
$doc->setFillColor(37, 99, 235);
$doc->rect(40, $baseY + 5, 40, 30, 'F');


// Always reset compositing state before continuing.
$doc->setAlpha(1.0, BlendMode::Normal);
$doc->setFillColor(255);


$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/gradients.pdf';
$doc->save($out);


echo "Created gradients.pdf\n";

邊界情況與陷阱

標題為「邊界情況與陷阱」的區段
  • 漸層端點重合時不會繪製任何內容。 當 w 或 h 使軸線塌縮成零尺寸的方框時，依 ISO 32000-2 會產生空的軸向 shading。請確認方框具有實際範圍。
  • 半徑必須為非負值。 傳入 radialGradient() 的負半徑是無效的。兩個半徑皆為零時不會繪製任何內容。
  • Alpha 會在多次繪製之間持續生效。 setAlpha(0.7, …) 會對後續每一次繪製持續生效，直到你重設它為止。在一段透明區塊之後，請還原為 setAlpha(1.0, BlendMode::Normal)，否則之後的內容會呈現褪色。
  • 混合模式需要有底圖。 像 Multiply 或 Screen 這類混合模式會與已繪製的內容進行合成。在空白頁面上其效果不可見，因此請先繪製一塊底圖。
  • PDF 2.0 的混合模式陣列已棄用。 NextPDF 會輸出單一混合模式名稱，也就是 PDF 2.0 的形式。舊式的陣列形式在規範中已棄用。

效能

標題為「效能」的區段

一個漸層就是一個 shading 物件加上一次填色。Alpha 與混合模式則是圖形狀態參數。每次使用各自的成本都是固定的，且兩者都在 2000 ms / 64 MB 的預算範圍之內。過程中不會發生點陣化，因此漸層仍是不受輸出尺寸影響的向量式 shading。

安全性注意事項

標題為「安全性注意事項」的區段

本範例只會繪製你的程式碼所提供的幾何圖形與顏色。過程中不會發生任何輸入剖析或網路存取。對於來自不受信任資料的顏色與座標值，請在使用前先加以驗證。

符合性

標題為「符合性」的區段
陳述規範條款參考 ID
ShadingType 2 為軸向，3 為放射狀。ISO 32000-2§8.7.4.3
軸向 Coords 為 [x0 y0 x1 y1]；端點重合時不會繪製任何內容。ISO 32000-2§8.7.4.5.3
放射狀 Coords 為 [x0 y0 r0 x1 y1 r1]；半徑 ≥ 0。ISO 32000-2§8.7.4.5.4
CA/ca 是 stroking/non-stroking 的 alpha 常數。ISO 32000-2§8.4.5
BM 是目前的混合模式。ISO 32000-2§11.3.5

可重現性設定檔 — 結構層級。 每次儲存時，trailer 的 /ID 與日期原子都會有所不同。測試載具會去除那些原子，再比對經 qpdf 正規化後的結構。本範例說明 NextPDF 如何產生這個結構。它並未對 ISO 32000-2 符合性做出全面性的聲明。

商業情境

標題為「商業情境」的區段

不適用。漸層、alpha 與混合模式都是核心功能。它們沒有任何 Premium gate（付費門檻）。

另請參閱

標題為「另請參閱」的區段