Pro sürüm

Chart — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF Pro Chart modülünün sözleşme düzeyindeki başvurusudur. Yüzey, NextPDF\Pro\Chart içindeki beş genel sınıftır: BarChart, LineChart ve PieChart oluşturucuları, ChartBox yerleştirme dikdörtgeni ve ChartColor değer nesnesi. Her oluşturucu bir çizim ilkelidir. Statik bir fabrika onu yaratır, akıcı with*() çağrıları onu yapılandırır ve render(ChartBox $box): string sağlanan dikdörtgen için PDF içerik akışı operatörleri döndürür. Çıktı yalnızca vektöreldir ve belirleyicidir: aynı girdi ve yapılandırma aynı baytları üretir. Yozlaşmış girdiler istisna fırlatmak yerine boş bir dize döndürür; böylece bir chart çevreleyen sayfayı asla bozmaz. Göreve yönelik görünüm yetenek sayfasında bulunur.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) içinde sunulur ve Pro katmanı lisans zarfıyla etkinleşir. Bu yetkilendirme olmadan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve lisans edinin.

Chart oluşturucuları, chart.* yetenek ailesi altında yetenek lisanslıdır. Yetenek lisanslı değilken, chart oluşturucuları kullanılamaz.

Genel API yüzeyi

composer require nextpdf/pro:^3

Sembol	Parametreler	Varsayılan davranış	Döndürür	Fırlattığı veya başarısız olduğu	Notlar
`BarChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Değerler float’a dönüştürülür	`self`	Fırlatmaz	Tek yapım yolu; yapıcı özeldir
`BarChart::withBarColor()`	`ChartColor $color`	Çubuk dolgusu; varsayılan palet girdisi 0	`self`	Fırlatmaz	Akıcı; alıcıyı değiştirir
`BarChart::withAxisColor()`	`ChartColor $color`	Eksen konturu; varsayılan `#333333`	`self`	Fırlatmaz	—
`BarChart::withBarGap()`	`float $gap`	Yuva genişliğinin bir kesri olarak boşluk; varsayılan `0.2`	`self`	Fırlatmaz	`0.0`–`0.9` aralığına sıkıştırılır; aralık dışı girdi reddedilmez, sıkıştırılır
`BarChart::withFontSize()`	`float $size`	Punto cinsinden etiket yazı tipi boyutu; varsayılan `7.0`	`self`	Fırlatmaz	—
`BarChart::render()`	`ChartBox $box`	Eksenler, çubuklar, kategori etiketleri, beş değer işareti	`string` operatörleri	Fırlatmaz; boş veri `''` döndürür	Pozitif olmayan bir maksimum `1.0`’e göre ölçeklenir
`LineChart::create()`	`list<string> $labels`	Serisiz chart	`self`	Fırlatmaz	Yapıcı özeldir
`LineChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Bir adsız seri ekler	`self`	Fırlatmaz	Tek serili kolaylık
`LineChart::addSeries()`	`string $name`, `list<int\|float> $values`, `?ChartColor $color = null`	`null` bir renk, seri dizinine göre paletten otomatik atanır	`self`	Fırlatmaz	Seri adı, açıklama kullanımı için ayrılmıştır
`LineChart::withAxisColor()`	`ChartColor $color`	Eksen konturu; varsayılan `#333333`	`self`	Fırlatmaz	—
`LineChart::withLineWidth()`	`float $width`	Seri kontur genişliği; varsayılan `1.5`	`self`	Fırlatmaz	—
`LineChart::withFontSize()`	`float $size`	Etiket yazı tipi boyutu; varsayılan `7.0`	`self`	Fırlatmaz	—
`LineChart::withDots()`	`bool $show`, `float $radius = 2.5`	Veri noktası işaretleyicileri; varsayılan olarak açık	`self`	Fırlatmaz	İşaretleyiciler Bezier ile yaklaştırılan daireler olarak çizilir
`LineChart::withGrid()`	`bool $show`	Yatay çeyrek ızgara; varsayılan olarak açık	`self`	Fırlatmaz	—
`LineChart::render()`	`ChartBox $box`	Izgara, eksenler, seri başına bir yol, etiketler	`string` operatörleri	Fırlatmaz; seri yoksa `''` döndürür	İki noktadan kısa bir seri hiçbir yol çizmez
`PieChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Oranlar, değer toplamından hesaplanır	`self`	Fırlatmaz	Yapıcı özeldir
`PieChart::withColors()`	`list<ChartColor> $colors`	Sırayla, dilim başına bir renk	`self`	Fırlatmaz	Eksik girdiler palete geri döner
`PieChart::withStrokeColor()`	`ChartColor $color`	Dilim ana hattı; varsayılan beyaz	`self`	Fırlatmaz	—
`PieChart::withFontSize()`	`float $size`	Etiket yazı tipi boyutu; varsayılan `7.0`	`self`	Fırlatmaz	—
`PieChart::withPercentages()`	`bool $show`	Yüzde etiketleri; varsayılan olarak açık	`self`	Fırlatmaz	Etiketler yalnızca 15 dereceden fazla süpüren dilimlerde işlenir
`PieChart::withLegend()`	`bool $show`	Sağ taraf açıklaması; varsayılan olarak açık	`self`	Fırlatmaz	Açıklama, kutu genişliğinden 80 punto ayırır
`PieChart::render()`	`ChartBox $box`	Sektörler, isteğe bağlı etiketler, isteğe bağlı açıklama	`string` operatörleri	Fırlatmaz; boş veri veya sıfır ya da altındaki bir toplam `''` döndürür	Yaylar en fazla 90 derecelik Bezier segmentlerine bölünür
`ChartBox::__construct()`	`float $x`, `float $y`, `float $width`, `float $height`	Punto cinsinden, PDF sol-alt kökeni	—	Fırlatmaz	`final readonly`; boyutlar doğrulanmaz
`ChartBox::fromUserSpace()`	`float $x`, `float $y`, `float $width`, `float $height`, `float $pageHeight`	Sol-üst-kökenli bir dikdörtgeni PDF koordinatlarına çevirir	`self`	Fırlatmaz	—
`ChartBox::right()`	yok	`x + width`	`float`	Fırlatmaz	Özellik değil, yöntem
`ChartBox::top()`	yok	`y + height`	`float`	Fırlatmaz	Özellik değil, yöntem
`ChartBox::inset()`	`float $left`, `float $bottom`, `float $right`, `float $top`	Verilen girintilerle küçültülmüş alt kutu	`self`	Fırlatmaz	Aşırı boyutlu girintiler negatif boyutlar verir; doğrulanmaz
`ChartColor::__construct()`	`float $r`, `float $g`, `float $b`, her biri `0.0`–`1.0`	—	—	Fırlatmaz	`final readonly`; bileşenler sıkıştırılmaz
`ChartColor::rgb()`	`int $r`, `int $g`, `int $b`, her biri `0`–`255`	Bileşenleri `0.0`–`1.0` aralığına ölçekler	`self`	Fırlatmaz	—
`ChartColor::hex()`	`string $hex`	`#` önekli veya yalın altı basamaklı hex kabul eder	`self`	Fırlatmaz	Eksik sondaki basamaklar sıfır olarak çözülür
`ChartColor::palette()`	`int $index`	Yerleşik 12 renkli palet	`self`	Negatif dizinde `TypeError`	Negatif olmayan dizinler modulo 12 sarılır
`ChartColor::strokeOperator()`	yok	Kontur renk operatörü (`RG`), üç ondalık	`string`	Fırlatmaz	Özellik değil, yöntem
`ChartColor::fillOperator()`	yok	Dolgu renk operatörü (`rg`), üç ondalık	`string`	Fırlatmaz	Özellik değil, yöntem

Giriş noktası imzaları

public static function fromData(array $labels, array $values): self
public function withBarColor(ChartColor $color): self
public function withAxisColor(ChartColor $color): self
public function withBarGap(float $gap): self
public function withFontSize(float $size): self
public function render(ChartBox $box): string

public static function create(array $labels): self
public static function fromData(array $labels, array $values): self
public function addSeries(string $name, array $values, ?ChartColor $color = null): self
public function withAxisColor(ChartColor $color): self
public function withLineWidth(float $width): self
public function withFontSize(float $size): self
public function withDots(bool $show, float $radius = 2.5): self
public function withGrid(bool $show): self
public function render(ChartBox $box): string

public static function fromData(array $labels, array $values): self
public function withColors(array $colors): self
public function withStrokeColor(ChartColor $color): self
public function withFontSize(float $size): self
public function withPercentages(bool $show): self
public function withLegend(bool $show): self
public function render(ChartBox $box): string

public function __construct(
    public float $x,
    public float $y,
    public float $width,
    public float $height,
)

public static function fromUserSpace(
    float $x,
    float $y,
    float $width,
    float $height,
    float $pageHeight,
): self

public function right(): float
public function top(): float
public function inset(float $left, float $bottom, float $right, float $top): self

public static function rgb(int $r, int $g, int $b): self
public static function hex(string $hex): self
public static function palette(int $index): self
public function strokeOperator(): string
public function fillOperator(): string

Davranış sözleşmesi

Ortak oluşturucu biçimi

Üç oluşturucu da tek bir yaşam döngüsünü izler: statik bir fabrika, akıcı yapılandırma, tek bir render() çağrısı. Yapılandırma yöntemleri alıcıyı değiştirir ve onu döndürür; oluşturucular değişmez değer nesneleri değildir. render(), yapılandırmayı değiştirmeden okur; böylece yapılandırılmış bir oluşturucu birkaç kutuya işlenebilir. Her işleme, çıktısını bir kaydet/geri yükle grafik durumu çiftiyle sarar; böylece chart durumu sayfaya asla sızmaz. Koordinatlar iki ondalıkla, renk bileşenleri üç ondalıkla yayılır; bu da çıktıyı bayt-kararlı tutar. Metin, yapılandırılan boyutta /ChartFont yazı tipi kaynak adı üzerinden işlenir; çağıran, hedef sayfanın kaynak sözlüğüne bu adla bir yazı tipi kaydeder. Etiket dizeleri, dize işlenenlerine girmeden önce ters eğik çizgi ve parantezleri kaçış karakteriyle işler. Oluşturucular hiçbir yeniden akış, kırpma veya kapsayıcı pazarlığı gerçekleştirmez: yerleştirme çağırana aittir.

Ölçekleme ve düzen

Bar ve line chart’ları, kutunun içinde sabit bir çizim girintisi ayırır: 40 punto sol, 20 alt, 10 sağ, 10 üst. Kalan çizim alanı, değerleri seri maksimumuna göre doğrusal olarak ölçekler. Sıfır veya altındaki bir maksimum, sıfıra bölmek yerine 1.0’e göre ölçeklenir; böylece tümü-sıfır veri, eksenleri sıfıra bölmeden düz içerikle işler. Her ikisi de X ve Y eksenlerini 0.5 punto genişlikte ve beş değer işaretini çeyrek konumlarda çizer. Bar chart’ları, bin ve bir milyonun üzerindeki işaret değerlerini K ve M sonekleriyle biçimlendirir; line chart’ları düz sayılar yazdırır.

Çubuk grafik

Her değer, çizim genişliği boyunca eşit bir yuva kaplar. Çubuk, yuvayı eksi yapılandırılmış boşluk kesri doldurur ve yuvada ortalanır. Kategori etiketleri, çizim alanının 12 punto altına çizilir.

Çizgi grafik

Izgara, etkinleştirildiğinde, eksenlerin ve serilerin altına açık gri (0.85 0.85 0.85 RG) dört yatay çeyrek çizgi çizer. Her seri, noktalarından geçen ve tüm çizim genişliğine yayılan bir çoklu çizgi çizer. İsteğe bağlı işaretleyiciler, her veri noktasında dört segmentli Bezier daireleri olarak çizilir. Seri renkleri, varsayılan olarak ekleme sırasına göre ardışık palet girdileridir.

Pasta grafik

Dilimler, pozitif X ekseninden başlayıp saat yönünün tersine süpürerek veri sırasında yerleşir. Her sektör yolu kapanır ve birleşik dolgu ve konturla (h B) boyanır; yaylar en fazla 90 derecelik Bezier segmentlerine bölünür. Yüzde etiketleri tam yüzdeye yuvarlanır ve yalnızca 15 dereceden fazla süpüren dilimlerde işlenir. Açıklama, etkinleştirildiğinde, sağda kutu genişliğinden 80 punto ayırır ve girdi başına 12 punto satır yüksekliğinde 8 puntoluk bir örnek işler. Yarıçap, kalan genişlik ile kutu yüksekliğinin küçüğünün yarısıdır, eksi 10 puntoluk bir kenar boşluğu.

Yerleştirme ve renk değer nesneleri

ChartBox, sol-alt kökenli, PDF kullanıcı birimlerinde (punto) değişmez bir dikdörtgendir. ChartBox::fromUserSpace(), sol-üst-kökenli bir dikdörtgeni sağlanan sayfa yüksekliğine göre çevirerek dönüştürür. inset() yeni, daha küçük bir kutu döndürür; right() ve top() erişimci yöntemlerdir. ChartColor kendi kendine yeterlidir ve Core renk sınıflarına bağlı değildir. 12 girdili paleti, çağıran hiçbiri sağlamadığında seri ve dilim renklerini atar.

Destek matrisi (kanıta dayalı)

Bir chart türü veya özellik, Verified değerini yalnızca bir pro/tests/** armatürü onu çalıştırdığında kazanır. Hiçbir harici standart chart’ları yönetmez; bu nedenle kanıt, birim düzeyinde davranışsal kapsamdır.

Chart türü / özellik	Durum	Kanıt (test yolu)	Güven	Notlar
Bar chart — render, eksenler, çubuk dikdörtgenleri, boşluk sıkıştırma, boş/tümü-sıfır veri, K/M değer biçimlendirme	Verified	`pro/tests/Unit/Chart/BarChartTest.php`; `BarChartArithmeticCoverageTest.php`; `BarChartBoundaryCoverageTest.php`	high	Grafik durumu sarmalama, eksen çizgileri, çubuk yüksekliği oranları, işaret sayısı ve biçimlendirme sınırları öne sürülür.
Line chart — tek ve çok serili, çizgi yolu, eksenler, noktalar, ızgara, tek nokta	Verified	`pro/tests/Unit/Chart/LineChartTest.php`; `LineChartCoverageTest.php`; `LineChartArithmeticCoverageTest.php`; `LineChartTypeCastCoverageTest.php`	high	Çok serili, tek noktalı çizgisiz, boş seri, ızgara ve nokta yolları kapsanır.
Pie chart — sektörler, Bezier segmentleme, yüzdeler, açıklama, sıfır/negatif toplam	Verified	`pro/tests/Unit/Chart/PieChartTest.php`; `PieChartArithmeticCoverageTest.php`; `PieChartBoundaryCoverageTest.php`	high	Sektör yolları, süpürme başına segment sayıları, 15 derecelik etiket eşiği, açıklama geometrisi ve boş-dize davranışı kapsanır.
`ChartBox` — koordinat dönüşümü (kullanıcı uzayından PDF’e), sayfa üst/alt, sıfır boyutlar, girinti	Verified	`pro/tests/Unit/Chart/ChartBoxTest.php`	high	Sayfa üstünde, altında ve sıfır-boyut kenarlarında sol-üst-kökenden sol-alt-kökene dönüşüm.
`ChartColor` — RGB ölçekleme, hex ayrıştırma, palet, kontur/dolgu operatörleri	Verified	`pro/tests/Unit/Chart/ChartColorTest.php`	high	0–255’ten 0–1’e ölçekleme, `#` önekli ve yalın hex, karışık büyük/küçük harf, 12 girdiden sonra palet sarması.
Oluşturucular arası gerileme sağlamlaştırması	Verified	`pro/tests/Unit/Chart/ChartCoverageTest.php`	high	Üç oluşturucu artı değer biçimlendirme aritmetiği arasında paylaşılan gerileme paketi.
bar/line/pie dışındaki chart türleri (area, scatter, stacked, donut vb.)	Not supported	—	high	Hiçbir oluşturucu sunulmaz. Modül yüzeyi tam olarak bar, line, pie’dir. Dürüstçe belirtilir: bu “her chart türü” değildir.

Dürüst sayı: Verified 6 satır, Claimed 0, Not supported 1 (bar, line, pie dışında herhangi bir chart türü).

Uç durumlar ve hata modları

Hiçbir oluşturucu veride fırlatmaz. Yozlaşmış girdi boş bir dizeye indirgenir: boş bar veya line verisi, boş bir seri listesi ve sıfır ya da altındaki bir pie toplamı hepsi '' döndürür.
İki noktadan az bir line serisi hiçbir yol ve işaretleyici çizmez; eksenler ve etiketler yine de işlenir.
Negatif çubuk değerleri reddedilmez; çubuk dikdörtgeni X ekseninin altına uzanır.
Etiket ve değer sayıları karşılıklı doğrulanmaz. Çağıran, eşleşen uzunlukta listeler sağlar.
Sıfır veya negatif boyutlu bir ChartBox kabul edilir ve yozlaşmış çıktı üretir; çağıranlar kutuyu boyutlandırmalıdır.
Oluşturucular kırpmaz. Aşırı boyutlu bir chart, çizim altı kategori etiketleri veya uzun bir açıklama, amaçlanan sayfa bölgesinden taşabilir.
Chart yazı tipi kaynak adı altında yazı tipi eksik olan bir sayfa, tanımsız bir kaynağa başvuran metin operatörleri bırakır; görüntüleyici davranışı o zaman tanımsızdır.
ChartColor::hex() hiçbir doğrulama gerçekleştirmez; altı basamaktan kısa girdi, eksik bileşenleri sıfır olarak çözer. ChartColor::palette(), negatif bir dizinde TypeError ile başarısız olur; çünkü PHP’nin negatif modulosu hiçbir palet anahtarını çözmez.
Modül hiçbir kriptografi gerçekleştirmez; FIPS modunun hiçbir chart’a özgü davranışı yoktur.

Uygunluk

Chart modülü PDF içerik akışı operatörleri yayar. Hiçbir harici chart, semboloji veya kriptografik standart çıktısını yönetmez; bu nedenle tek uygunluk yüzeyi, yayılan operatör akışıdır.

İddia	Standart	Madde
Yayılan grafikler içerik akışı operatör modelini izler; çıktı, kaydedilmiş ve geri yüklenmiş bir grafik durumunun içine yerleşir.	ISO 32000-2	§8.1
Çubuklar, çizgiler, sektörler ve işaretleyiciler yol nesneleridir: oluşturma `m` veya `re` ile başlar ve bir yol boyama operatörüyle sonlanır.	ISO 32000-2	§8.5.2
Etiketler metin nesneleri olarak işlenir: konum `BT`’den sonra belirlenir ve glifler `Tj` metin gösterme operatörüyle boyanır.	ISO 32000-2	§9.2.2, §9.4.3

Tüm maddeler açıklanarak aktarılmıştır; bu sayfa hiçbir normatif metni yeniden üretmez. Bunlar yeterlilik ifadeleridir, sertifikalar değildir; NextPDF hiçbir sertifika tutmaz ve hiçbirini vermez. Akışın doğru işlenmesi ayrıca, çevreleyen belgenin iyi biçimlendirilmiş olmasına bağlıdır; bu da belge yazarının sorumluluğudur.

Geliştirme notları

Beş sınıfın tümü @since 1.9.0 taşır ve nextpdf/pro 3.1.0 içinde günceldir.
Modül kendi kendine yeterlidir: oluşturucular yalnızca ChartBox ve ChartColor’a bağlıdır, hiçbir Core bağlaşımı yoktur.
Belirleyici çıktı, chart içeren belgeleri yeniden üretilebilir, diff-kararlı ve imzalamak veya arşivlemek için güvenli tutar.
Chart barındıran her sayfa için chart yazı tipi kaynak adı altında bir kez yazı tipi kaydedin.
Yapılandırılmış bir oluşturucuyu kutular arasında serbestçe yeniden kullanın; render() hiçbir durum değişikliği gerçekleştirmez.
Test kanıtı pro/tests/Unit/Chart/ altında bulunur; destek matrisi her Verified satırını kendi paketine bağlar.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, çalışma kılavuzu dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

Chart (yetenek) — göreve yönelik genel bakış, kurulum ve kod örnekleri.
Barcode — Derinlemesine başvuru — kendi kanıta dayalı destek matrisine sahip kardeş Pro çizim yüzeyi.