Pro edycja

Chart — szczegółowa dokumentacja referencyjna

W skrócie

Ta strona to dokumentacja modułu Chart w NextPDF Pro na poziomie kontraktu. Powierzchnię tworzy pięć klas publicznych w NextPDF\Pro\Chart: renderery BarChart, LineChart i PieChart, prostokąt rozmieszczenia ChartBox oraz obiekt wartości ChartColor. Każdy renderer jest prymitywem rysującym. Statyczna fabryka go tworzy, płynne wywołania with*() go konfigurują, a render(ChartBox $box): string zwraca operatory strumienia zawartości PDF dla podanego prostokąta. Wynik jest wyłącznie wektorowy i deterministyczny: identyczne wejście i konfiguracja dają identyczne bajty. Zdegenerowane dane wejściowe zwracają pusty ciąg znaków zamiast zgłaszać wyjątek, więc wykres nigdy nie psuje otaczającej strony. Widok zorientowany na zadania znajduje się na stronie możliwości.

Dostępność i licencjonowanie

Ta możliwość jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej możliwości. Porównaj edycje i uzyskaj licencję.

Renderery wykresów są licencjonowane w ramach rodziny możliwości chart.*. Gdy możliwość nie jest licencjonowana, renderery wykresów są niedostępne.

Powierzchnia publicznego API

composer require nextpdf/pro:^3

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem	Uwagi
`BarChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Wartości są rzutowane na float	`self`	Nie zgłasza wyjątku	Jedyna ścieżka konstrukcji; konstruktor jest prywatny
`BarChart::withBarColor()`	`ChartColor $color`	Wypełnienie słupka; domyślnie wpis 0 palety	`self`	Nie zgłasza wyjątku	Płynne; modyfikuje odbiorcę
`BarChart::withAxisColor()`	`ChartColor $color`	Obrys osi; domyślnie `#333333`	`self`	Nie zgłasza wyjątku	—
`BarChart::withBarGap()`	`float $gap`	Odstęp jako ułamek szerokości slotu; domyślnie `0.2`	`self`	Nie zgłasza wyjątku	Ograniczany do `0.0`–`0.9`; wejście poza zakresem jest ograniczane, nie odrzucane
`BarChart::withFontSize()`	`float $size`	Rozmiar czcionki etykiet w punktach; domyślnie `7.0`	`self`	Nie zgłasza wyjątku	—
`BarChart::render()`	`ChartBox $box`	Osie, słupki, etykiety kategorii, pięć znaczników wartości	operatory `string`	Nie zgłasza wyjątku; puste dane zwracają `''`	Niedodatnie maksimum jest skalowane względem `1.0`
`LineChart::create()`	`list<string> $labels`	Wykres bez serii	`self`	Nie zgłasza wyjątku	Konstruktor jest prywatny
`LineChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Dodaje jedną nienazwaną serię	`self`	Nie zgłasza wyjątku	Udogodnienie dla pojedynczej serii
`LineChart::addSeries()`	`string $name`, `list<int\|float> $values`, `?ChartColor $color = null`	Kolor `null` jest automatycznie przypisywany z palety według indeksu serii	`self`	Nie zgłasza wyjątku	Nazwa serii jest zarezerwowana do użytku w legendzie
`LineChart::withAxisColor()`	`ChartColor $color`	Obrys osi; domyślnie `#333333`	`self`	Nie zgłasza wyjątku	—
`LineChart::withLineWidth()`	`float $width`	Szerokość obrysu serii; domyślnie `1.5`	`self`	Nie zgłasza wyjątku	—
`LineChart::withFontSize()`	`float $size`	Rozmiar czcionki etykiet; domyślnie `7.0`	`self`	Nie zgłasza wyjątku	—
`LineChart::withDots()`	`bool $show`, `float $radius = 2.5`	Znaczniki punktów danych; domyślnie włączone	`self`	Nie zgłasza wyjątku	Znaczniki rysowane jako okręgi aproksymowane krzywymi Béziera
`LineChart::withGrid()`	`bool $show`	Pozioma siatka kwartylowa; domyślnie włączona	`self`	Nie zgłasza wyjątku	—
`LineChart::render()`	`ChartBox $box`	Siatka, osie, jedna ścieżka na serię, etykiety	operatory `string`	Nie zgłasza wyjątku; brak serii zwraca `''`	Seria krótsza niż dwa punkty nie rysuje ścieżki
`PieChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Proporcje obliczane na podstawie sumy wartości	`self`	Nie zgłasza wyjątku	Konstruktor jest prywatny
`PieChart::withColors()`	`list<ChartColor> $colors`	Jeden kolor na wycinek, w kolejności	`self`	Nie zgłasza wyjątku	Brakujące wpisy korzystają z palety
`PieChart::withStrokeColor()`	`ChartColor $color`	Kontur wycinka; domyślnie biały	`self`	Nie zgłasza wyjątku	—
`PieChart::withFontSize()`	`float $size`	Rozmiar czcionki etykiet; domyślnie `7.0`	`self`	Nie zgłasza wyjątku	—
`PieChart::withPercentages()`	`bool $show`	Etykiety procentowe; domyślnie włączone	`self`	Nie zgłasza wyjątku	Etykiety renderowane tylko na wycinkach o rozpiętości większej niż 15 stopni
`PieChart::withLegend()`	`bool $show`	Legenda po prawej stronie; domyślnie włączona	`self`	Nie zgłasza wyjątku	Legenda rezerwuje 80 punktów szerokości pola
`PieChart::render()`	`ChartBox $box`	Sektory, opcjonalne etykiety, opcjonalna legenda	operatory `string`	Nie zgłasza wyjątku; puste dane lub suma na poziomie zera bądź poniżej zwracają `''`	Łuki dzielone na segmenty Béziera o rozpiętości najwyżej 90 stopni
`ChartBox::__construct()`	`float $x`, `float $y`, `float $width`, `float $height`	Początek w lewym dolnym rogu PDF, w punktach	—	Nie zgłasza wyjątku	`final readonly`; wymiary nie są walidowane
`ChartBox::fromUserSpace()`	`float $x`, `float $y`, `float $width`, `float $height`, `float $pageHeight`	Odwraca prostokąt z początkiem w lewym górnym rogu na współrzędne PDF	`self`	Nie zgłasza wyjątku	—
`ChartBox::right()`	brak	`x + width`	`float`	Nie zgłasza wyjątku	Metoda, nie właściwość
`ChartBox::top()`	brak	`y + height`	`float`	Nie zgłasza wyjątku	Metoda, nie właściwość
`ChartBox::inset()`	`float $left`, `float $bottom`, `float $right`, `float $top`	Podpole zmniejszone o podane wcięcia	`self`	Nie zgłasza wyjątku	Zbyt duże wcięcia dają ujemne wymiary; nie są walidowane
`ChartColor::__construct()`	`float $r`, `float $g`, `float $b`, każdy `0.0`–`1.0`	—	—	Nie zgłasza wyjątku	`final readonly`; składowe nie są ograniczane
`ChartColor::rgb()`	`int $r`, `int $g`, `int $b`, każdy `0`–`255`	Skaluje składowe do `0.0`–`1.0`	`self`	Nie zgłasza wyjątku	—
`ChartColor::hex()`	`string $hex`	Akceptuje hex sześciocyfrowy z prefiksem `#` lub bez	`self`	Nie zgłasza wyjątku	Brakujące końcowe cyfry są dekodowane jako zero
`ChartColor::palette()`	`int $index`	Wbudowana 12-kolorowa paleta	`self`	`TypeError` dla ujemnego indeksu	Nieujemne indeksy zawijają modulo 12
`ChartColor::strokeOperator()`	brak	Operator koloru obrysu (`RG`), trzy miejsca po przecinku	`string`	Nie zgłasza wyjątku	Metoda, nie właściwość
`ChartColor::fillOperator()`	brak	Operator koloru wypełnienia (`rg`), trzy miejsca po przecinku	`string`	Nie zgłasza wyjątku	Metoda, nie właściwość

Sygnatury punktów wejścia

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

Kontrakt zachowania

Wspólny kształt renderera

Wszystkie trzy renderery mają jeden cykl życia: statyczna fabryka, płynna konfiguracja, jedno wywołanie render(). Metody konfiguracyjne modyfikują odbiorcę i zwracają go; renderery nie są niezmiennymi obiektami wartości. render() odczytuje konfigurację bez jej modyfikowania, więc jeden skonfigurowany renderer może renderować do kilku pól. Każde renderowanie opakowuje swój wynik w parę zapisu/przywrócenia stanu grafiki, więc stan wykresu nigdy nie przenika do strony. Współrzędne są emitowane z dwoma miejscami po przecinku, a składowe koloru z trzema, co utrzymuje bajtową stabilność wyniku. Tekst renderowany jest przez nazwę zasobu czcionki /ChartFont w skonfigurowanym rozmiarze; wywołujący rejestruje czcionkę pod tą nazwą w słowniku zasobów docelowej strony. Ciągi etykiet zabezpieczają znak ukośnika wstecznego i nawiasy przed wejściem do operandów ciągów. Renderery nie wykonują żadnego ponownego przepływu, przycinania ani negocjacji kontenera: rozmieszczeniem zarządza wywołujący.

Skalowanie i układ

Wykresy słupkowe i liniowe rezerwują stałe wcięcie obszaru wykresu wewnątrz pola: 40 punktów od lewej, 20 od dołu, 10 od prawej, 10 od góry. Pozostały obszar wykresu skaluje wartości liniowo względem maksimum serii. Maksimum równe zero lub poniżej jest zamiast tego skalowane względem 1.0, więc dane złożone z samych zer renderują osie z płaską zawartością, zamiast dzielić przez zero. Oba rysują osie X i Y o szerokości 0,5 punktu oraz pięć znaczników wartości w pozycjach kwartyli. Wykresy słupkowe formatują wartości znaczników z sufiksami K i M powyżej tysiąca i miliona; wykresy liniowe drukują zwykłe liczby.

Wykres słupkowy

Każda wartość zajmuje równy slot na szerokości wykresu. Słupek wypełnia slot pomniejszony o skonfigurowany ułamek odstępu i jest wyśrodkowany w slocie. Etykiety kategorii rysowane są 12 punktów poniżej obszaru wykresu.

Wykres liniowy

Siatka, gdy jest włączona, rysuje cztery poziome linie kwartylowe w jasnoszarym kolorze (0.85 0.85 0.85 RG) pod osiami i seriami. Każda seria rysuje jedną łamaną przez swoje punkty, obejmującą pełną szerokość wykresu. Opcjonalne znaczniki rysowane są jako czterosegmentowe okręgi Béziera w każdym punkcie danych. Kolory serii domyślnie przyjmują kolejne wpisy palety w kolejności wstawiania.

Wykres kołowy

Wycinki układane są w kolejności danych, zaczynając od dodatniej osi X i zataczając łuk w kierunku przeciwnym do ruchu wskazówek zegara. Każda ścieżka sektora zamyka się i jest malowana z połączonym wypełnieniem i obrysem (h B); łuki dzielone są na segmenty Béziera o rozpiętości najwyżej 90 stopni. Etykiety procentowe zaokrąglane są do pełnych procentów i renderowane tylko na wycinkach o rozpiętości większej niż 15 stopni. Legenda, gdy jest włączona, rezerwuje 80 punktów szerokości pola po prawej stronie i renderuje 8-punktową próbkę na wpis przy 12-punktowej wysokości wiersza. Promień jest połową mniejszej z pozostałej szerokości i wysokości pola, pomniejszoną o margines 10 punktów.

Obiekty wartości rozmieszczenia i koloru

ChartBox to niezmienny prostokąt w jednostkach użytkownika PDF (punkty) z początkiem w lewym dolnym rogu. ChartBox::fromUserSpace() konwertuje prostokąt z początkiem w lewym górnym rogu, odwracając go względem podanej wysokości strony. inset() zwraca nowe, mniejsze pole; right() i top() są metodami dostępowymi. ChartColor jest samowystarczalny i nie zależy od klas kolorów Core. Jego 12-elementowa paleta przypisuje kolory serii i wycinków, gdy wywołujący ich nie poda.

Macierz wsparcia (poparta dowodami)

Typ wykresu lub funkcja uzyskuje status Zweryfikowane tylko wtedy, gdy ćwiczy je fikstura pro/tests/**. Żaden zewnętrzny standard nie reguluje wykresów, więc dowodem jest pokrycie behawioralne na poziomie jednostkowym.

Typ wykresu / funkcja	Status	Dowód (ścieżka testu)	Pewność	Uwagi
Wykres słupkowy — renderowanie, osie, prostokąty słupków, ograniczanie odstępu, dane puste/wszystkie-zerowe, formatowanie wartości K/M	Zweryfikowane	`pro/tests/Unit/Chart/BarChartTest.php`; `BarChartArithmeticCoverageTest.php`; `BarChartBoundaryCoverageTest.php`	wysoka	Owinięcie stanu grafiki, linie osi, proporcje wysokości słupków, liczba znaczników i granice formatowania potwierdzone.
Wykres liniowy — jedno- i wieloseryjny, ścieżka linii, osie, kropki, siatka, pojedynczy punkt	Zweryfikowane	`pro/tests/Unit/Chart/LineChartTest.php`; `LineChartCoverageTest.php`; `LineChartArithmeticCoverageTest.php`; `LineChartTypeCastCoverageTest.php`	wysoka	Wiele serii, brak linii dla pojedynczego punktu, pusta seria, ścieżki siatki i kropek objęte.
Wykres kołowy — sektory, segmentacja Béziera, procenty, legenda, suma zero/ujemna	Zweryfikowane	`pro/tests/Unit/Chart/PieChartTest.php`; `PieChartArithmeticCoverageTest.php`; `PieChartBoundaryCoverageTest.php`	wysoka	Ścieżki sektorów, liczby segmentów na rozpiętość, próg etykiety 15 stopni, geometria legendy i zachowanie pustego ciągu objęte.
`ChartBox` — konwersja współrzędnych (przestrzeń użytkownika na PDF), góra/dół strony, zerowe wymiary, inset	Zweryfikowane	`pro/tests/Unit/Chart/ChartBoxTest.php`	wysoka	Konwersja z początku w lewym górnym rogu na początek w lewym dolnym rogu na górze, dole i przy krawędziach zerowych wymiarów strony.
`ChartColor` — skalowanie RGB, parsowanie hex, paleta, operatory obrysu/wypełnienia	Zweryfikowane	`pro/tests/Unit/Chart/ChartColorTest.php`	wysoka	Skalowanie 0–255 na 0–1, hex z prefiksem `#` i bez, mieszana wielkość liter, zawijanie palety po 12 wpisach.
Utwardzenie regresji między rendererami	Zweryfikowane	`pro/tests/Unit/Chart/ChartCoverageTest.php`	wysoka	Wspólny zestaw regresji obejmujący trzy renderery oraz arytmetykę formatowania wartości.
Typy wykresów poza słupkowym/liniowym/kołowym (warstwowy, punktowy, skumulowany, pierścieniowy itp.)	Nieobsługiwane	—	wysoka	Nie jest dostarczany żaden renderer. Powierzchnia modułu to dokładnie słupkowy, liniowy, kołowy. Powiedziane uczciwie: to nie jest „każdy typ wykresu”.

Uczciwy bilans: Zweryfikowane: 6 wierszy, Deklarowane: 0, Nieobsługiwane: 1 (dowolny typ wykresu inny niż słupkowy, liniowy, kołowy).

Przypadki brzegowe i tryby awarii

Żaden renderer nie zgłasza wyjątku na danych. Zdegenerowane wejście degraduje się do pustego ciągu znaków: puste dane słupkowe lub liniowe, pusta lista serii oraz suma kołowa na poziomie zera bądź poniżej — wszystkie zwracają ''.
Seria liniowa o mniej niż dwóch punktach nie rysuje ścieżki ani znaczników; osie i etykiety nadal się renderują.
Ujemne wartości słupków nie są odrzucane; prostokąt słupka rozciąga się poniżej osi X.
Liczby etykiet i wartości nie są weryfikowane krzyżowo. Wywołujący dostarcza listy o zgodnej długości.
ChartBox o zerowych lub ujemnych wymiarach jest akceptowany i daje zdegenerowany wynik; wywołujący muszą ustawić rozmiar pola.
Renderery nie przycinają. Zbyt duży wykres, jego etykiety kategorii pod obszarem wykresu lub długa legenda mogą przepełnić zamierzony obszar strony.
Strona bez czcionki pod nazwą zasobu czcionki wykresu pozostawia operatory tekstu odwołujące się do niezdefiniowanego zasobu; zachowanie przeglądarki jest wtedy niezdefiniowane.
ChartColor::hex() nie wykonuje żadnej walidacji; wejście krótsze niż sześć cyfr dekoduje brakujące składowe jako zero. ChartColor::palette() kończy się TypeError dla ujemnego indeksu, ponieważ ujemne modulo w PHP nie rozwiązuje żadnego klucza palety.
Moduł nie wykonuje żadnej kryptografii; tryb FIPS nie ma zachowania specyficznego dla wykresów.

Konformancja

Moduł Chart emituje operatory strumienia zawartości PDF. Żaden zewnętrzny standard wykresów, symboliki ani kryptograficzny nie reguluje jego wyniku, więc jedyną powierzchnią konformancji jest emitowany strumień operatorów.

Twierdzenie	Standard	Klauzula
Emitowana grafika podąża za modelem operatorów strumienia zawartości; wynik zagnieżdża się wewnątrz zapisanego i przywróconego stanu grafiki.	ISO 32000-2	§8.1
Słupki, linie, sektory i znaczniki są obiektami ścieżek: konstrukcja zaczyna się od `m` lub `re` i kończy operatorem malowania ścieżki.	ISO 32000-2	§8.5.2
Etykiety renderowane są jako obiekty tekstowe: pozycja ustalana jest po `BT`, a glify malowane operatorem pokazywania tekstu `Tj`.	ISO 32000-2	§9.2.2, §9.4.3

Wszystkie klauzule są parafrazowane; ta strona nie odtwarza żadnego tekstu normatywnego. Są to oświadczenia o możliwościach, nie certyfikaty; NextPDF nie posiada żadnego certyfikatu i żadnego nie udziela. Poprawne renderowanie strumienia zależy również od tego, czy otaczający dokument jest poprawnie sformowany, za co odpowiada autor dokumentu.

Uwagi programistyczne

Wszystkie pięć klas nosi @since 1.9.0 i są aktualne w nextpdf/pro 3.1.0.
Moduł jest samowystarczalny: renderery zależą wyłącznie od ChartBox i ChartColor, bez sprzężenia z Core.
Deterministyczny wynik sprawia, że dokumenty z wykresami są odtwarzalne, stabilne w porównaniach diff i bezpieczne do podpisania lub zarchiwizowania.
Zarejestruj czcionkę pod nazwą zasobu czcionki wykresu raz na każdą stronę, która zawiera wykresy.
Ponownie używaj skonfigurowanego renderera w różnych polach bez ograniczeń; render() nie wykonuje żadnej mutacji stanu.
Dowody z testów znajdują się w pro/tests/Unit/Chart/; macierz wsparcia zakotwicza każdy wiersz Zweryfikowane do jego zestawu.

Granica publikacji

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

Zobacz także

Chart (możliwość) — przegląd zorientowany na zadania, instalacja i przykłady kodu.
Barcode — szczegółowa dokumentacja referencyjna — siostrzana powierzchnia rysująca Pro z własną popartą dowodami macierzą wsparcia.