Vektorgrafiken zeichnen — Formen, Farben und Linienstile

Auf einen Blick

Dieses Recipe zeichnet gefüllte und umrissene Primitive: Rechtecke, abgerundete Rechtecke, Kreise, Ellipsen und Linien. Für jedes davon legen Sie die Füllfarbe, die Kontur- bzw. Zeichenfarbe und die Linienbreite fest. Das Recipe orientiert sich an examples/06-colors-and-drawing.php.

Jedes Primitiv wird auf ein ISO 32000-2-Pfadobjekt abgebildet. Ein Pfadobjekt ist eine Form, die aus Linien- und Kurvensegmenten aufgebaut ist. Es endet mit einem Painting-Operator, der entscheidet, ob die Form umrissen, gefüllt oder beides wird.

Installation

composer require nextpdf/core:^3

Es ist keine optionale Extension erforderlich. Die Zeichen- und Farb-API ist seit 1.0.0 stabil und wird in der 8.1–8.4-Backport-Matrix unterstützt.

Konzeptioneller Überblick

Erst den Zustand setzen, dann zeichnen. setFillColor(), setDrawColor() und setLineWidth() aktualisieren den Grafikzustand. Der nächste Aufruf von rect(), circle(), ellipse(), roundedRect() oder line() verwendet diesen Zustand. Die Form-Methoden nehmen ein Style-Argument entgegen: 'F' füllt, 'S' umreißt (der Standard), und 'DF'/'FD' bewirkt beides. Intern ist ein gefülltes Rechteck der Pfadkonstruktions-Operator re, gefolgt vom Füll-Painting-Operator. ISO 32000-2 §8.5.3 legt S zum Umreißen und f zum Füllen als die wichtigsten Pfad-Painting-Operatoren fest.

Farben werden als Gerätefarben angegeben. setFillColor(r, g, b) wählt DeviceRGB. ISO 32000-2 §8.6.4.3 definiert rg als den nicht umreißenden DeviceRGB-Farboperator und g als das DeviceGray-Äquivalent. Ein setFillColor($v) mit nur einem Argument setzt einen Graustufenwert. Die Linienbreite ist standardmäßig 1.0, und das Strichmuster ist standardmäßig eine durchgezogene Linie (§8.4.3.6).

API-Oberfläche

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

rect(float $x, float $y, float $w, float $h, string $style = 'S'): static
roundedRect(float $x, float $y, float $w, float $h, float $r, string $style = 'S'): static
circle(float $x, float $y, float $r, string $style = 'S'): static
ellipse(float $x, float $y, float $rx, float $ry, string $style = 'S'): static
line(float $x1, float $y1, float $x2, float $y2): static
setFillColor(int $r, int $g = -1, int $b = -1): static / setDrawColor(...)
setLineWidth(float $width): static

Codebeispiel — Schnellstart

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

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

$doc->setFillColor(30, 58, 138);
$doc->rect(20, 30, 60, 40, 'F');          // filled rectangle

$doc->setDrawColor(217, 119, 6);
$doc->setLineWidth(1.0);
$doc->circle(140, 50, 20, 'S');           // stroked circle

$doc->setLineWidth(0.3);
$doc->line(20, 90, 190, 90);              // thin rule

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

Codebeispiel — Produktion

Dies ist das vollständige, Harness-fertige Beispiel. Es berücksichtigt NEXTPDF_COOKBOOK_OUTPUT und fügt keine eigene Entropie hinzu.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Colors and Drawing');
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Colors and Drawing', newLine: true);
$doc->ln(5);

// --- Filled rectangles: set fill colour, then draw with style 'F' ---
$palette = [
    [30, 58, 138], [217, 119, 6], [30, 27, 75],
    [239, 66, 35], [21, 128, 61],
];
$x = 15.0;
$rowY = $doc->getY();
foreach ($palette as [$r, $g, $b]) {
    $doc->setFillColor($r, $g, $b);
    $doc->rect($x, $rowY, 30, 20, 'F');
    $x += 35.0;
}
$doc->ln(28);

// --- Outlined shapes: set draw colour + line width, draw with 'S' ---
$doc->setDrawColor(30, 58, 138);
$doc->setLineWidth(0.5);
$y = $doc->getY();
$doc->rect(15, $y, 30, 25, 'S');
$doc->roundedRect(55, $y, 30, 25, 5, 'S');
$doc->circle(110, $y + 12.5, 12.5, 'S');
$doc->ellipse(150, $y + 12.5, 18, 10, 'S');
$doc->ln(33);

// --- Lines at three widths ---
$y = $doc->getY();
$doc->setDrawColor(0);
$doc->setLineWidth(0.2);
$doc->line(15, $y, 195, $y);
$doc->setLineWidth(0.8);
$doc->line(15, $y + 5, 195, $y + 5);
$doc->setLineWidth(1.5);
$doc->line(15, $y + 12, 195, $y + 12);

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

echo "Created vector.pdf\n";

Sonderfälle & Stolperfallen

Standardmäßig wird die Form umrissen. Wenn Sie das Style-Argument weglassen, wird die Form umrissen ('S'). Eine Form, die unsichtbar wirkt, wird meist ohne gesetzte Zeichenfarbe gezeichnet oder mit der Hintergrundfarbe der Seite gefüllt. Übergeben Sie 'F', um sie zu füllen.
Der Farbzustand bleibt erhalten. setFillColor() bleibt wirksam, bis Sie die Füllfarbe ändern. Setzen Sie sie zurück (zum Beispiel mit setFillColor(255)), bevor der nächste unabhängige Block folgt, sonst wird die Farbe übernommen.
Graustufe gegenüber der RGB-Überladung. setFillColor(128) ist ein Graustufenwert. setFillColor(128, 0, 0) ist RGB. Die Aufrufform mit einem Argument ist nicht „rot 128“.
Die Y-Achse verläuft in der API von oben nach unten. Die Zeichenhelfer verwenden den Ursprung oben links des Dokuments. Die Engine bildet das für Sie auf den PDF-Benutzerraum unten links ab.

Performance

Jedes Primitiv besteht aus einer Handvoll Content-Stream-Operatoren. Tausende Formen pro Seite bleiben deutlich innerhalb des Budgets von 2000 ms / 64 MB. Die Kosten wachsen linear mit der Anzahl der Primitive. Es gibt keine Rasterung, daher bleibt die Ausgabe vektorbasiert.

Sicherheitshinweise

Dieses Recipe zeichnet nur die Geometrie, die Ihr Code angibt. Es parst keine Eingaben und greift nicht auf das Netzwerk zu. Prüfen Sie jede Koordinate, die aus nicht vertrauenswürdigen Daten stammt, auf ihren Wertebereich. Eine Bereichsprüfung verhindert, dass ein böswilliger Wert Markierungen weit außerhalb der Seite platziert.

Konformität

Aussage	Spezifikation	Klausel
Ein Pfadobjekt besteht aus Linien, Rechtecken und Bézier-Kurven und endet mit einem Painting-Operator.	ISO 32000-2	§8.5
`S` umreißt einen Pfad und `f` füllt ihn.	ISO 32000-2	§8.5.3
`rg` setzt die nicht umreißende DeviceRGB-Farbe; `g` setzt DeviceGray.	ISO 32000-2	§8.6.4.3
Der Anfangswert des Strichmusters ist `[] 0`, eine durchgezogene Linie.	ISO 32000-2	§8.4.3.6

Reproduzierbarkeitsprofil — strukturell. Vektorzeichnen hat keine eigene Entropie. Dennoch trägt jedes gespeicherte Dokument ein Trailer-/ID sowie Datums-Atome. ISO 32000-2 §8.3.4 stellt außerdem fest, dass die genaue Anordnung der Grafikzustands-Operatoren keine semantische Bedeutung hat, sodass ein Normalisierer äquivalenten Zustand umordnen darf. Die präzise Aussage ist strukturelle Gleichheit nach der qpdf-Normalisierung. Dieses Recipe beschreibt, wie NextPDF die Struktur erzeugt. Es behauptet keine pauschale ISO 32000-2-Konformität.

Kommerzieller Kontext

Nicht zutreffend. Vektorzeichnen ist eine Core-Funktion ohne Premium-Gate.