Melukis gradien serta menggunakan transparansi dan mode pembauran

Sekilas pandang

Isi area dengan gradien aksial (linear) atau radial dengan dua perhentian. Kemudian, kompositkan bentuk-bentuk yang saling bertumpang tindih menggunakan alpha konstan dan mode pembauran opsional. Kode ini mengikuti examples/25-gradients.php dan examples/20-transparency.php.

Gradien adalah shading ISO 32000-2. linearGradient() menghasilkan shading Type 2 (aksial), sedangkan radialGradient() menghasilkan shading Type 3 (radial). Transparansi menggunakan konstanta alpha pada graphics-state. setAlpha() mengatur nilai ca non-stroking dan nilai CA stroking.

Instalasi

composer require nextpdf/core:^3

Ekstensi opsional tidak diperlukan. API gradien, alpha, dan mode pembauran telah stabil sejak 1.0.0 dan berjalan pada matriks backport 8.1–8.4.

Tinjauan konseptual

linearGradient(x, y, w, h, start, end) melukis pembauran warna sepanjang sumbu kotak di antara dua perhentian Color. ISO 32000-2 mendefinisikan Coords untuk shading aksial sebagai [x0 y0 x1 y1]. Jika titik-titik ujung berimpit, tidak ada yang dilukis. radialGradient(...) membaurkan warna di antara dua lingkaran. Coords radial adalah [x0 y0 r0 x1 y1 r1], dan kedua jari-jari harus ≥ 0.

setAlpha($alpha, $mode) mengatur opasitas konstan untuk pelukisan berikutnya. Argumen pertama adalah konstanta alpha (ca/CA). Argumen kedua memilih mode pembauran (BM dalam model pencitraan transparan). Atur ulang alpha ke 1.0 dan mode pembauran ke Normal sebelum menggambar konten yang tidak terkait.

Permukaan API

Permukaan API dihasilkan dari PHPDoc. Resep ini menggunakan metode berikut:

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() menyediakan perhentian gradien.
setFillColor(...) mengatur warna yang dikompositkan oleh alpha dan mode pembauran.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Ini adalah contoh lengkap yang siap untuk harness. Contoh ini menghormati NEXTPDF_COOKBOOK_OUTPUT dan tidak menambahkan entropi sendiri.

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

Kasus tepi & jebakan

Titik-titik ujung gradien yang berimpit tidak melukis apa pun. Kotak berukuran nol, ketika w atau h meruntuhkan sumbu, menghasilkan shading aksial kosong sesuai ISO 32000-2. Pastikan kotak tersebut memiliki luas.
Jari-jari harus non-negatif. Jari-jari negatif yang diteruskan ke radialGradient() tidak valid. Dua jari-jari nol tidak melukis apa pun.
Alpha tetap berlaku di seluruh pelukisan. setAlpha(0.7, …) tetap berlaku untuk setiap operasi pelukisan berikutnya sampai Anda mengatur ulangnya. Pulihkan setAlpha(1.0, BlendMode::Normal) setelah blok transparan, atau konten selanjutnya akan tampak pudar.
Mode pembauran memerlukan latar belakang. Mode pembauran seperti Multiply atau Screen bekerja terhadap apa yang sudah digambar. Di atas halaman kosong, efeknya tidak terlihat, jadi gambar latar belakang terlebih dahulu.
Array mode pembauran PDF 2.0 sudah usang. NextPDF menghasilkan satu nama mode pembauran tunggal, yaitu bentuk PDF 2.0. Spesifikasi tersebut mengusangkan bentuk array warisan.

Kinerja

Gradien adalah satu objek shading ditambah satu isian. Alpha dan mode pembauran merupakan parameter graphics-state. Masing-masing memiliki biaya konstan per penggunaan, dan keduanya tetap berada dalam anggaran 2000 ms / 64 MB. Tidak terjadi rasterisasi, sehingga gradien tetap menjadi shading yang tidak bergantung pada resolusi.

Catatan keamanan

Resep ini hanya melukis geometri dan warna yang disediakan oleh kode Anda. Resep ini tidak melakukan penguraian input atau akses jaringan apa pun. Validasi nilai warna dan koordinat dari data yang tidak tepercaya sebelum menggunakannya.

Kesesuaian

Pernyataan	Spesifikasi	Klausa
`ShadingType` 2 adalah aksial, 3 adalah radial.	ISO 32000-2	§8.7.4.3
`Coords` aksial adalah `[x0 y0 x1 y1]`; titik-titik ujung yang berimpit tidak melukis apa pun.	ISO 32000-2	§8.7.4.5.3
`Coords` radial adalah `[x0 y0 r0 x1 y1 r1]`; jari-jari ≥ 0.	ISO 32000-2	§8.7.4.5.4
`CA`/`ca` adalah konstanta alpha stroking/non-stroking.	ISO 32000-2	§8.4.5
`BM` adalah mode pembauran saat ini.	ISO 32000-2	§11.3.5

Profil reproduktibilitas — struktural. /ID trailer dan atom tanggal bervariasi setiap kali disimpan. Harness menghapus atom-atom tersebut, lalu membandingkan struktur yang telah dinormalisasi oleh qpdf. Resep ini menjelaskan cara NextPDF menghasilkan struktur tersebut. Resep ini tidak membuat klaim menyeluruh tentang kesesuaian ISO 32000-2.

Konteks komersial

Tidak berlaku. Gradien, alpha, dan mode pembauran merupakan kapabilitas Core. Semuanya tidak dibatasi oleh gerbang Premium.