Menggambar grafis vektor — bentuk, warna, dan gaya garis

Sekilas pandang

Gunakan resep ini untuk menggambar primitif yang diisi dan diberi garis luar: persegi panjang, persegi panjang bersudut membulat, lingkaran, elips, dan garis. Untuk setiap bentuk, Anda menetapkan warna isian, warna goresan, dan lebar garis. Resep ini mengikuti examples/06-colors-and-drawing.php.

Setiap primitif dipetakan ke objek lintasan ISO 32000-2. Objek lintasan adalah bentuk yang dibangun dari segmen garis dan kurva. Objek ini diakhiri oleh operator pewarnaan yang memberi tahu penampil untuk memberi goresan, mengisi, atau melakukan keduanya.

Pemasangan

composer require nextpdf/core:^3

Anda tidak memerlukan ekstensi opsional. API untuk menggambar dan memberi warna telah stabil sejak 1.0.0, dan berjalan pada matriks backport 8.1–8.4.

Tinjauan konseptual

Tetapkan keadaan, lalu gambar. setFillColor(), setDrawColor(), dan setLineWidth() memperbarui keadaan grafik. Pemanggilan rect(), circle(), ellipse(), roundedRect(), atau line() berikutnya menggunakan keadaan tersebut. Metode bentuk menerima argumen gaya: 'F' untuk mengisi, 'S' untuk memberi goresan (nilai standar), dan 'DF'/'FD' untuk melakukan keduanya. Secara internal, persegi panjang berisi adalah operator konstruksi lintasan re yang diikuti oleh operator pewarnaan isian. ISO 32000-2 §8.5.3 menetapkan S untuk memberi goresan dan f untuk mengisi sebagai operator pewarnaan lintasan utama.

Warna yang digunakan adalah warna perangkat. setFillColor(r, g, b) memilih DeviceRGB. ISO 32000-2 §8.6.4.3 mendefinisikan rg sebagai operator warna non-goresan DeviceRGB dan g sebagai padanan DeviceGray. setFillColor($v) dengan satu argumen menetapkan tingkat keabuan. Lebar garis defaultnya 1.0, dan pola garis putus-putus defaultnya adalah garis utuh (§8.4.3.6).

Permukaan API

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

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

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Contoh lengkap yang siap untuk harness ini mengikuti NEXTPDF_COOKBOOK_OUTPUT dan tidak menambahkan entropi apa pun dari dirinya sendiri.

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

Kasus tepi & jebakan

Gaya default adalah goresan. Jika Anda menghilangkan argumen gaya, bentuk akan diberi goresan ('S'). Bentuk yang tampak tidak terlihat biasanya digambar tanpa warna goresan yang ditetapkan, atau diisi dengan warna latar halaman. Berikan 'F' untuk mengisinya.
Keadaan warna tetap bertahan. setFillColor() tetap berlaku sampai Anda mengubahnya. Atur ulang nilainya, misalnya dengan setFillColor(255), sebelum blok berikutnya yang tidak terkait; jika tidak, warna akan terus terbawa.
Keabuan versus overload RGB. setFillColor(128) adalah tingkat keabuan. setFillColor(128, 0, 0) adalah RGB. Varian satu argumen bukanlah “merah 128”.
Sumbu Y bergerak dari atas ke bawah dalam API. Pembantu menggambar menggunakan titik asal kiri atas dokumen. Mesin memetakannya ke ruang pengguna PDF yang bertitik asal kiri bawah untuk Anda.

Kinerja

Setiap primitif menghasilkan sejumlah kecil operator aliran konten. Ribuan bentuk per halaman tetap berada jauh di dalam anggaran 2000 ms / 64 MB. Biaya bertambah secara linear seiring jumlah primitif. Tidak ada rasterisasi, sehingga keluaran tetap berupa vektor.

Catatan keamanan

Resep ini hanya menggambar geometri yang ditentukan oleh kode Anda. Resep ini tidak mengurai masukan apa pun dan tidak mengakses jaringan. Periksa rentang setiap koordinat yang berasal dari data tak tepercaya. Pemeriksaan ini mencegah nilai berbahaya menempatkan objek gambar jauh di luar halaman.

Kesesuaian

Pernyataan	Spesifikasi	Klausul
Objek lintasan adalah garis, persegi panjang, dan kurva Bézier yang berakhir pada operator pewarnaan.	ISO 32000-2	§8.5
`S` memberi goresan dan `f` mengisi sebuah lintasan.	ISO 32000-2	§8.5.3
`rg` menetapkan warna non-goresan DeviceRGB; `g` menetapkan DeviceGray.	ISO 32000-2	§8.6.4.3
Nilai awal pola garis putus-putus adalah `[] 0`, sebuah garis utuh.	ISO 32000-2	§8.4.3.6

Profil keterulangan — struktural. Penggambaran vektor tidak memiliki entropi sendiri. Meski begitu, setiap dokumen yang disimpan membawa /ID trailer dan atom tanggal. ISO 32000-2 §8.3.4 juga menyatakan bahwa susunan persis operator keadaan grafik tidak memiliki makna semantik, sehingga penormal dapat mengurutkan ulang keadaan yang setara. Klaim yang didukung adalah kesetaraan struktural setelah normalisasi qpdf. Resep ini menjelaskan bagaimana NextPDF menghasilkan struktur tersebut. Resep ini tidak menyatakan kesesuaian ISO 32000-2 sebagai klaim menyeluruh.

Konteks komersial

Tidak berlaku. Penggambaran vektor adalah kemampuan Core tanpa pembatas Premium.