Verläufe zeichnen und Transparenz mit Mischmodi nutzen

Auf einen Blick

Füllen Sie einen Bereich mit einem axialen (linearen) oder radialen Verlauf mit zwei Stopps und überlagern Sie anschließend einander überlappende Formen mit konstanter Deckkraft und einem optionalen Mischmodus. Der Code orientiert sich an examples/25-gradients.php und examples/20-transparency.php.

Ein Verlauf ist eine ISO 32000-2-Schattierung. linearGradient() erzeugt eine Schattierung vom Typ 2 (axial), und radialGradient() erzeugt eine Schattierung vom Typ 3 (radial). Transparenz wird über die Alpha-Konstante des Grafikzustands gesteuert. setAlpha() setzt den Non-stroking-Wert ca und den Stroking-Wert CA.

Installation

composer require nextpdf/core:^3

Es ist keine optionale Erweiterung erforderlich. Die API für Verläufe, Alpha und Mischmodi ist seit 1.0.0 stabil und wird in der Backport-Matrix 8.1–8.4 unterstützt.

Konzeptioneller Überblick

linearGradient(x, y, w, h, start, end) zeichnet in der Box entlang ihrer Achse einen Farbverlauf zwischen zwei Color-Stopps. ISO 32000-2 definiert die Coords einer axialen Schattierung als [x0 y0 x1 y1]. Fallen die Endpunkte zusammen, wird nichts gezeichnet. radialGradient(...) blendet zwischen zwei Kreisen. Die radialen Coords lauten [x0 y0 r0 x1 y1 r1], und beide Radien müssen ≥ 0 sein.

setAlpha($alpha, $mode) setzt die konstante Deckkraft für die nachfolgende Zeichnung. Das erste Argument ist die Alpha-Konstante (ca/CA). Das zweite Argument wählt den Mischmodus aus (BM im transparenten Abbildungsmodell). Setzen Sie Alpha auf 1.0 und den Mischmodus auf Normal zurück, bevor Sie andere Inhalte zeichnen.

API-Oberfläche

Die API-Oberfläche wird automatisch aus PHPDoc generiert. Dieses Recipe verwendet diese Methoden:

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() liefern die Verlaufsstopps.
setFillColor(...) setzt die Farbe, auf die Alpha und Mischmodus angewendet werden.

Codebeispiel — Schnellstart

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

Codebeispiel — Produktion

Dies ist das vollständige, für das Harness vorbereitete Beispiel. Es berücksichtigt NEXTPDF_COOKBOOK_OUTPUT und legt keine eigene Entropie fest.

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

Randfälle & Fallstricke

Zusammenfallende Verlaufsendpunkte zeichnen nichts. Eine Box ohne Größe, bei der w oder h die Achse zusammenfallen lässt, ergibt gemäß ISO 32000-2 eine leere axiale Schattierung. Stellen Sie sicher, dass die Box eine Ausdehnung hat.
Radien dürfen nicht negativ sein. Ein negativer Radius bei radialGradient() ist ungültig. Zwei Radien von null zeichnen nichts.
Alpha bleibt über Zeichnungen hinweg erhalten. setAlpha(0.7, …) bleibt für alle späteren Zeichnungen wirksam, bis Sie es zurücksetzen. Stellen Sie nach einem transparenten Block setAlpha(1.0, BlendMode::Normal) wieder her, sonst werden spätere Inhalte blass dargestellt.
Ein Mischmodus braucht einen Hintergrund. Ein Mischmodus wie Multiply oder Screen wirkt auf das, was bereits gezeichnet ist. Auf einer leeren Seite ist der Effekt unsichtbar, zeichnen Sie also zuerst einen Hintergrund.
Das PDF 2.0-Mischmodus-Array ist veraltet. NextPDF gibt einen einzelnen Mischmodus-Namen aus; das entspricht der PDF 2.0-Form. Die alte Array-Form ist in der Spezifikation veraltet.

Performance

Ein Verlauf besteht aus einem Schattierungsobjekt plus einer Füllung. Alpha und Mischmodus sind Parameter des Grafikzustands. Beides verursacht pro Verwendung konstanten Aufwand und bleibt innerhalb des Budgets von 2000 ms / 64 MB. Es findet keine Rasterung statt, daher bleiben Verläufe auflösungsunabhängige Schattierungen.

Sicherheitshinweise

Dieses Recipe zeichnet nur die Geometrie und Farben, die Ihr Code liefert. Eingaben werden nicht geparst, und es erfolgt kein Netzwerkzugriff. Validieren Sie Farb- und Koordinatenwerte aus nicht vertrauenswürdigen Daten, bevor Sie sie verwenden.

Konformität

Aussage	Spezifikation	Abschnitt
`ShadingType` 2 ist axial, 3 ist radial.	ISO 32000-2	§8.7.4.3
Axiale `Coords` lauten `[x0 y0 x1 y1]`; zusammenfallende Endpunkte zeichnen nichts.	ISO 32000-2	§8.7.4.5.3
Radiale `Coords` lauten `[x0 y0 r0 x1 y1 r1]`; Radien ≥ 0.	ISO 32000-2	§8.7.4.5.4
`CA`/`ca` sind die Alpha-Konstanten für stroking/non-stroking.	ISO 32000-2	§8.4.5
`BM` ist der aktuelle Mischmodus.	ISO 32000-2	§11.3.5

Reproduzierbarkeitsprofil — strukturell. Der Trailer /ID und die Datumsatome variieren bei jedem Speichern. Das Harness entfernt diese Atome und vergleicht anschließend die qpdf-normalisierte Struktur. Dieses Recipe beschreibt, wie NextPDF die Struktur erzeugt. Es erhebt keinen pauschalen Anspruch auf ISO 32000-2-Konformität.

Kommerzieller Kontext

Nicht zutreffend. Verläufe, Alpha und Mischmodi sind Core-Funktionen. Sie sind nicht durch ein Premium-Gate geschützt.