Pro edycja

Wykres

W skrócie

NextPDF Pro renderuje wykresy słupkowe, liniowe i kołowe bezpośrednio na stronie PDF jako wektorowe operatory zawartości. Nie ma kroku rasteryzacji ani zależności od przeglądarki bezgłowej, więc wynik jest deterministyczny i odtwarzalny.

Instalacja

composer require nextpdf/pro:^3

Przegląd koncepcyjny

Moduł Chart udostępnia trzy natywne renderery wykresów. Każdy z nich jest samodzielnym prymitywem rysującym: renderuje w obrębie podanego przez Ciebie prostokątnego pola o ustalonym rozmiarze, bez przepływu, bez świadomości kontenera i bez negocjacji układu. Ty pozycjonujesz pole; renderer je wypełnia.

Wykres słupkowy — pionowy wykres słupkowy z konfigurowalnym kolorem słupków, kolorem osi, odstępem między słupkami oraz rozmiarem czcionki etykiet.
Wykres liniowy — jedno- lub wieloseryjny wykres liniowy z kolorem na serię, opcjonalnymi znacznikami punktów danych, opcjonalną siatką oraz konfigurowalną grubością linii.
Wykres kołowy — wykres kołowy z automatycznym przypisaniem palety, opcjonalnymi etykietami procentowymi oraz opcjonalną legendą.

Każdy renderer ma ten sam kształt: fabrykę fromData(...), płynną konfigurację with*() oraz wywołanie render(ChartBox $box): string, które zwraca operatory strumienia zawartości PDF. Wynik jest deterministyczny — identyczne dane wejściowe i konfiguracja dają identyczne operatory, dzięki czemu dokumenty z wykresami pozostają odtwarzalne i bezpieczne do podpisania lub zarchiwizowania.

Ponieważ renderery emitują operatory wektorowe, a nie obrazy, wykresy pozostają ostre przy dowolnym powiększeniu i nie dodają do dokumentu żadnego ładunku rastrowego.

Dlaczego działa to w ten sposób

Kluczową decyzją jest emitowanie natywnych operatorów wektorowych PDF zamiast rasteryzowania obrazu lub sterowania przeglądarką bezgłową. Ten wybór czyni wynik deterministycznym: identyczne dane i konfiguracja zawsze dają bajtowo identyczne operatory. Deterministyczne operatory sprawiają, że dokument z wykresem jest odtwarzalny, a przez to bezpieczny do podpisania lub zarchiwizowania. Rezygnacja z zewnętrznego renderera usuwa też zależność procesową, więc przepustowość skaluje się wraz z liczbą punktów danych, a nie z kosztem uruchamiania przeglądarki. Każdy renderer opakowuje swoje operatory w parę stanu grafiki q/Q i nigdy nie przepływa, więc komponuje się przewidywalnie i tanio.

Tło projektowe: Generowanie dokumentów o wysokim wolumenie.

Powierzchnia API

composer require nextpdf/pro:^3

Publiczna powierzchnia modułu Chart to pięć klas w NextPDF\Pro\Chart:

BarChart — fromData(), withBarColor(), withAxisColor(), withBarGap(), withFontSize(), render().
LineChart — create(), fromData(), addSeries(), withAxisColor(), withLineWidth(), withFontSize(), withDots(), withGrid(), render().
PieChart — fromData(), withColors(), withStrokeColor(), withFontSize(), withPercentages(), withLegend(), render().
ChartBox — prostokąt rozmieszczenia; fromUserSpace() przekształca prostokąt przestrzeni użytkownika o początku w lewym górnym rogu na początek PDF w lewym dolnym rogu; inset() dla dopełnienia.
ChartColor — rgb(), hex(), palette(), a także emitery operatorów obrysu/wypełnienia.

Przykład kodu — Szybki start

use NextPDF\Pro\Chart\BarChart;
use NextPDF\Pro\Chart\ChartBox;

$box = ChartBox::fromUserSpace(72, 72, 400, 240, pageHeight: 842);
$stream = BarChart::fromData(['Q1', 'Q2', 'Q3', 'Q4'], [100, 200, 150, 300])
    ->render($box);
// $stream is appended to the target page content.

Przykład kodu — Produkcja

use NextPDF\Pro\Chart\ChartBox;
use NextPDF\Pro\Chart\ChartColor;
use NextPDF\Pro\Chart\LineChart;

$box = ChartBox::fromUserSpace(72, 72, 460, 260, pageHeight: 842)
    ->inset(8, 8, 8, 8);

$stream = LineChart::create(['Jan', 'Feb', 'Mar', 'Apr'])
    ->addSeries('Revenue', [120, 180, 150, 220], ChartColor::hex('#336699'))
    ->addSeries('Cost', [80, 90, 110, 130], ChartColor::palette(1))
    ->withGrid(true)
    ->withDots(true, 2.5)
    ->withLineWidth(1.2)
    ->render($box);

Przypadki brzegowe i pułapki

Puste dane zwracają pusty ciąg znaków zamiast zgłaszać wyjątek, więc brak zbioru danych renderuje nic zamiast psuć stronę.
Wykres kołowy o zerowej lub ujemnej sumie zwraca pusty ciąg znaków.
Seria liniowa z pojedynczym punktem nie rysuje odcinka linii (pojedynczy punkt nie ma ścieżki).
ChartBox o zerowych wymiarach nie renderuje niczego sensownego; ustaw rozmiar pola przed renderowaniem.
Renderery nie przycinają do pola; podaj pole, które mieści się w obszarze strony, jaki zamierzasz wykorzystać.

Wydajność

Renderowanie jest jednoprzebiegowe i liniowe względem liczby punktów danych. Nie ma rasteryzacji, bufora obrazu ani zewnętrznego procesu. Rozmiar emitowanego ciągu operatorów ogranicza koszt pamięci. Wieloseryjne wykresy liniowe skalują się liniowo względem łącznej liczby punktów we wszystkich seriach.

Uwagi dotyczące bezpieczeństwa

Renderery wykresów przyjmują wyłącznie dane liczbowe i etykiety; nie obliczają ani nie wykonują danych wejściowych. Renderery emitują etykiety jako operatory tekstowe PDF i nigdy ich nie interpretują. Moduł nie loguje żadnych danych wykresu; aplikacja musi oczyścić wrażliwe etykiety przed wykreśleniem.

Konformancja

Wykresy nie podlegają żadnej zewnętrznej normie; wynik to strumień zawartości PDF renderowany na stronie zgodnie z semantyką strumienia zawartości ISO 32000-2. Ten moduł nie ma powierzchni konformancji symboliki ani kryptografii.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz obsługiwaną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.