Vektör grafikleri çizme — şekiller, renkler ve çizgi stilleri

Bir bakışta

Dolgulu ve konturlu ilkel şekiller çizmek için bu tarifi kullanın: dikdörtgenler, yuvarlatılmış dikdörtgenler, daireler, elipsler ve çizgiler. Her şekil için dolgu rengini, kontur rengini ve çizgi genişliğini siz ayarlarsınız. Bu tarif examples/06-colors-and-drawing.php dosyasını izler.

Her ilkel şekil bir ISO 32000-2 yol nesnesine karşılık gelir. Yol nesnesi, çizgi ve eğri parçalarından oluşturulan bir şekildir. Görüntüleyiciye şeklin konturunu çizmesini, içini doldurmasını veya ikisini birden yapmasını bildiren bir boyama işleciyle sona erer.

Kurulum

composer require nextpdf/core:^3

İsteğe bağlı bir uzantı gerekmez. Çizim ve renk API’si, 1.0.0 sürümünden bu yana kararlıdır ve 8.1–8.4 geriye taşıma matrisinde çalışır.

Kavramsal genel bakış

Önce durumu ayarlayın, sonra çizin. setFillColor(), setDrawColor() ve setLineWidth() grafik durumunu günceller. Bir sonraki rect(), circle(), ellipse(), roundedRect() veya line() çağrısı da bu durumu kullanır. Şekil yöntemleri bir stil argümanı alır: 'F' doldurur, 'S' kontur çizer (varsayılan) ve 'DF'/'FD' ikisini birden yapar. Dahili olarak, dolgulu bir dikdörtgen yol oluşturma re işleci ve ardından gelen dolgu boyama işlecinden oluşur. ISO 32000-2 §8.5.3, kontur için S ve dolgu için f işleçlerini başlıca yol boyama işleçleri olarak belirtir.

Renkler aygıt renkleridir. setFillColor(r, g, b) DeviceRGB’yi seçer. ISO 32000-2 §8.6.4.3, rg işlecini DeviceRGB kontur dışı renk işleci, g işlecini de DeviceGray karşılığı olarak tanımlar. Tek argümanlı setFillColor($v) bir gri tonu ayarlar. Çizgi genişliği varsayılan olarak 1.0’dır; kesik çizgi deseni ise varsayılan olarak düz çizgidir (§8.4.3.6).

API yüzeyi

API yüzeyi PHPDoc’tan türetilir. Bu tarif şu yöntemleri kullanır:

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

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

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

Kod örneği — üretim

Bu eksiksiz, test ortamında çalıştırmaya hazır örnek NEXTPDF_COOKBOOK_OUTPUT değişkenine uyar ve kendi entropisini eklemez.

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

Sınır durumları ve tuzaklar

Varsayılan stil kontur çizmektir. Stil argümanını atlarsanız şeklin konturu çizilir ('S'). Görünmüyormuş gibi duran bir şekil genellikle hiçbir çizim rengi ayarlanmadan çizilmiştir veya sayfa arka plan rengiyle doldurulmuştur. Doldurmak için 'F' geçirin.
Renk durumu kalıcıdır. setFillColor() siz değiştirene kadar geçerli kalır. Sonraki bağımsız bloktan önce, örneğin setFillColor(255) ile sıfırlayın; aksi takdirde renk taşınır.
Gri ve RGB aşırı yüklemelerini ayırt edin. setFillColor(128) bir gri tonudur. setFillColor(128, 0, 0) ise RGB’dir. Tek argümanlı biçim “kırmızı 128” anlamına gelmez.
API’de Y ekseni yukarıdan aşağıya ilerler. Çizim yardımcıları belgenin sol üst köşesini başlangıç noktası olarak kullanır. Motor bunu sizin yerinize PDF’in sol alt kökenli kullanıcı uzayına eşler.

Performans

Her ilkel şekil, içerik akışına yalnızca birkaç işleç ekler. Sayfa başına binlerce şekil bile 2000 ms / 64 MB bütçesinin rahatlıkla içinde kalır. Maliyet, ilkel şekil sayısıyla doğrusal artar. Rasterleştirme yapılmaz; bu nedenle çıktı vektör olarak kalır.

Güvenlik notları

Bu tarif yalnızca kodunuzun belirttiği geometriyi çizer. Hiçbir girdiyi ayrıştırmaz ve hiçbir ağ erişimi yapmaz. Güvenilmeyen verilerden gelen tüm koordinatları aralık denetiminden geçirin. Bu denetim, kötü niyetli bir değerin çizimi sayfanın çok dışına taşımasını engeller.

Uyumluluk

İfade	Spesifikasyon	Madde
Yol nesnesi, bir boyama işleciyle sona eren çizgiler, dikdörtgenler ve Bézier eğrilerinden oluşur.	ISO 32000-2	§8.5
`S` bir yolun konturunu çizer; `f` ise yolu doldurur.	ISO 32000-2	§8.5.3
`rg` DeviceRGB kontur dışı rengini ayarlar; `g` DeviceGray’i ayarlar.	ISO 32000-2	§8.6.4.3
Kesik çizgi deseninin başlangıç değeri `[] 0`’dır ve düz çizgi anlamına gelir.	ISO 32000-2	§8.4.3.6

Yeniden üretilebilirlik profili — yapısal. Vektör çiziminin kendine ait hiçbir entropisi yoktur. Yine de kaydedilen her belge bir treyler /ID ve tarih atomları taşır. ISO 32000-2 §8.3.4 ayrıca grafik durumu işleçlerinin tam sıralamasının anlamsal önem taşımadığını belirtir; bu nedenle bir normalleştirici eşdeğer durumu yeniden sıralayabilir. Desteklenen iddia, qpdf normalleştirmesi sonrasında yapısal eşitliktir. Bu tarif, NextPDF’in yapıyı nasıl ürettiğini açıklar. Genel bir iddia olarak ISO 32000-2 uyumluluğunu öne sürmez.

Ticari bağlam

Uygulanamaz. Vektör çizim, Premium kısıtlaması bulunmayan bir Core yeteneğidir.