Renk geçişleri çizin; saydamlık ve karışım modları kullanın

Bir bakışta

Bir alanı iki duraklı eksenel (doğrusal) ya da radyal renk geçişiyle doldurun. Ardından üst üste binen şekilleri sabit alfa ve isteğe bağlı bir karışım moduyla birleştirin. Kod, examples/25-gradients.php ve examples/20-transparency.php dosyalarındaki akışı izler.

Renk geçişi, ISO 32000-2 kapsamındaki bir gölgelendirmedir. linearGradient() bir Type 2 (eksenel) gölgelendirme üretir; radialGradient() ise bir Type 3 (radyal) gölgelendirme üretir. Saydamlık, grafik durumu alfa sabitini kullanır. setAlpha() çizgi dışı (non-stroking) ca değerini ve çizgi (stroking) CA değerini ayarlar.

Kurulum

composer require nextpdf/core:^3

İsteğe bağlı bir uzantıya ihtiyacınız yoktur. Renk geçişi, alfa ve karışım modu API’si 1.0.0 sürümünden beri kararlıdır ve 8.1–8.4 backport matrisinde çalışır.

Kavramsal genel bakış

linearGradient(x, y, w, h, start, end), kutunun ekseni boyunca iki Color durağı arasında renk geçişi çizer. ISO 32000-2, eksenel bir gölgelendirmenin Coords değerini [x0 y0 x1 y1] olarak tanımlar. Uç noktalar çakışırsa hiçbir şey çizilmez. radialGradient(...) iki daire arasında geçiş oluşturur. Radyal Coords değeri [x0 y0 r0 x1 y1 r1] biçimindedir ve her iki yarıçap da ≥ 0 olmalıdır.

setAlpha($alpha, $mode), kendisinden sonra gelen çizim için sabit bir opaklık ayarlar. İlk argüman alfa sabitidir (ca/CA). İkinci argüman karışım modunu seçer (saydam görüntüleme modelinde BM). Bu ayarlardan etkilenmemesi gereken içeriği çizmeden önce alfayı 1.0 değerine, karışım modunu da Normal değerine sıfırlayın.

API yüzeyi

API yüzeyi PHPDoc’tan oluşturulur. Bu tarifte şu yöntemler kullanılır:

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() renk geçişi durakları sağlar.
setFillColor(...), alfa ve karışım modunun birleştirdiği rengi ayarlar.

Kod örneği — hızlı başlangıç

<?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');

Kod örneği — üretim

Bu örnek eksiksizdir ve test koşumunda çalışmaya hazırdır. NEXTPDF_COOKBOOK_OUTPUT değişkenine uyar ve kendisi hiçbir entropi eklemez.

<?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";

Uç durumlar ve dikkat edilecek noktalar

Çakışan renk geçişi uç noktaları hiçbir şey çizmez. w ya da h değerinin ekseni daralttığı sıfır boyutlu bir kutu, ISO 32000-2 uyarınca boş bir eksenel gölgelendirme üretir. Kutunun bir boyuta sahip olduğunu doğrulayın.
Yarıçaplar negatif olmamalıdır. radialGradient() içine verilen negatif yarıçap geçersizdir. İki sıfır yarıçap hiçbir şey çizmez.
Alfa, çizimler arasında kalıcıdır. setAlpha(0.7, …) siz sıfırlayana kadar sonraki her çizim için geçerli kalır. Saydam bir bloğun ardından setAlpha(1.0, BlendMode::Normal) değerini geri yükleyin; aksi takdirde sonraki içerik soluk görünür.
Bir karışım modu bir arka plana ihtiyaç duyar. Multiply veya Screen gibi bir karışım modu, halihazırda çizilmiş içerikle birleşir. Boş sayfada etkisi görünmeyeceği için önce bir arka plan çizin.
PDF 2.0 karışım modu dizisi kullanımdan kaldırılmıştır. NextPDF, PDF 2.0 biçimi olan tek bir karışım modu adı üretir. Belirtim eski dizi biçimini kullanımdan kaldırır.

Performans

Bir renk geçişi, bir gölgelendirme nesnesi ve bir dolgudan oluşur. Alfa ve karışım modu, grafik durumu parametreleridir. Her birinin kullanım başına sabit bir maliyeti vardır ve ikisi de 2000 ms / 64 MB bütçesi içinde kalır. Rasterleştirme yapılmaz; bu nedenle renk geçişleri çözünürlükten bağımsız gölgelendirmeler olarak kalır.

Güvenlik notları

Bu tarif yalnızca kodunuzun sağladığı geometri ve renkleri çizer. Herhangi bir girdi ayrıştırması ya da ağ erişimi gerçekleştirmez. Güvenilmeyen verilerden gelen renk ve koordinat değerlerini kullanmadan önce doğrulayın.

Uyumluluk

İfade	Belirtim	Madde
`ShadingType` 2 eksenel, 3 radyaldir.	ISO 32000-2	§8.7.4.3
Eksenel `Coords` değeri `[x0 y0 x1 y1]` şeklindedir; çakışan uç noktalar hiçbir şey çizmez.	ISO 32000-2	§8.7.4.5.3
Radyal `Coords` değeri `[x0 y0 r0 x1 y1 r1]` biçimindedir; yarıçaplar ≥ 0.	ISO 32000-2	§8.7.4.5.4
`CA`/`ca`, stroking/non-stroking alfa sabitleridir.	ISO 32000-2	§8.4.5
`BM` geçerli karışım modudur.	ISO 32000-2	§11.3.5

Yeniden üretilebilirlik profili — yapısal. Treyler /ID ve tarih atomları her kaydetmede değişir. Test koşumu bu atomları çıkarır, ardından qpdf ile normalleştirilmiş yapıyı karşılaştırır. Bu tarif, NextPDF uygulamasının yapıyı nasıl ürettiğini açıklar. Genel bir ISO 32000-2 uyumluluğu iddiasında bulunmaz.

Ticari bağlam

Geçerli değil. Renk geçişleri, alfa ve karışım modları Core yetenekleridir. Bunlar için herhangi bir Premium kısıtlaması yoktur.