Pro редакция

Chart

Краткий обзор

NextPDF Pro отрисовывает столбчатые, линейные и круговые диаграммы прямо на страницу PDF как векторные операторы содержимого. Этап растеризации отсутствует, как и зависимость от headless-браузера, поэтому результат детерминирован и воспроизводим.

Установка

composer require nextpdf/pro:^3

Концептуальный обзор

Модуль Chart предоставляет три встроенных отрисовщика диаграмм. Каждый — самодостаточный примитив рисования: он отрисовывается внутри заданного вами фиксированного прямоугольного бокса, без перекомпоновки, без учёта контейнера и без согласования макета. Вы размещаете бокс; отрисовщик заполняет его.

Столбчатая диаграмма — вертикальная столбчатая диаграмма с настраиваемым цветом столбцов, цветом осей, зазором между столбцами и размером шрифта подписей.
Линейная диаграмма — линейная диаграмма с одним или несколькими рядами, с цветом для каждого ряда, необязательными маркерами точек данных, необязательной сеткой и настраиваемой толщиной линии.
Круговая диаграмма — круговая диаграмма с автоматическим назначением палитры, необязательными процентными подписями и необязательной легендой.

Каждый отрисовщик устроен одинаково: фабрика fromData(...), текучая настройка with*() и вызов render(ChartBox $box): string, который возвращает операторы потока содержимого PDF. Результат детерминирован — одинаковые входные данные и конфигурация дают одинаковые операторы, благодаря чему документы с диаграммами воспроизводимы и их безопасно подписывать или архивировать.

Поскольку отрисовщики выводят векторные операторы, а не изображения, диаграммы остаются чёткими при любом масштабе и не добавляют в документ растровую нагрузку.

Почему это работает именно так

Ключевое решение — выводить встроенные векторные операторы PDF, а не растеризовать изображение или запускать headless-браузер. Этот выбор делает результат детерминированным: одинаковые данные и конфигурация всегда дают побайтово идентичные операторы. Детерминированные операторы сохраняют воспроизводимость документа с диаграммами и, как следствие, делают его безопасным для подписи или архивирования. Отказ от внешнего отрисовщика также убирает зависимость от процесса, поэтому пропускная способность масштабируется с числом точек данных, а не со стоимостью запуска браузера. Каждый отрисовщик оборачивает свои операторы в пару графического состояния q/Q и никогда не выполняет перекомпоновку, поэтому он компонуется предсказуемо и дёшево.

Проектный контекст: Генерация документов большого объёма.

Поверхность API

composer require nextpdf/pro:^3

Публичная поверхность Chart — это пять классов в 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 — прямоугольник размещения; fromUserSpace() преобразует прямоугольник пользовательского пространства с началом координат в левом верхнем углу в начало координат PDF в левом нижнем углу; inset() для отступов.
ChartColor — rgb(), hex(), palette(), плюс эмиттеры операторов обводки/заливки.

Пример кода — быстрый старт

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.

Пример кода — продакшн

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

Граничные случаи и подводные камни

Пустые данные возвращают пустую строку, а не вызывают исключение, поэтому отсутствующий набор данных ничего не отрисовывает вместо того, чтобы сломать страницу.
Круговая диаграмма с нулевой или отрицательной суммой возвращает пустую строку.
Линейный ряд с единственной точкой не рисует отрезок линии (у одной точки нет траектории).
ChartBox с нулевыми размерами не отрисовывает ничего осмысленного; задавайте размер бокса перед отрисовкой.
Отрисовщики не обрезают по боксу; задавайте бокс, который помещается в нужную область страницы.

Производительность

Отрисовка выполняется за один проход и линейна по числу точек данных. Нет растеризации, нет буфера изображения и нет внешнего процесса. Размер выводимой строки операторов ограничивает затраты памяти. Многорядные линейные диаграммы масштабируются линейно по суммарному числу точек во всех рядах.

Замечания по безопасности

Отрисовщики диаграмм потребляют только числовые данные и подписи; они не вычисляют и не выполняют входные данные. Отрисовщики выводят подписи как текстовые операторы PDF и никогда их не интерпретируют. Модуль не записывает в журнал данные диаграмм; приложение должно очищать конфиденциальные подписи перед построением диаграммы.

Соответствие

Диаграммы не регулируются внешним стандартом; результат — поток содержимого PDF, отрисованный на страницу согласно семантике потоков содержимого ISO 32000-2. У этого модуля нет поверхности соответствия по символике или криптографии.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов выходят за рамки.