Pro 版本

Chart

速览

NextPDF Pro 将柱状图、折线图和饼图以矢量内容运算符的形式，直接绘制到 PDF 页面中。这里没有栅格化步骤，也没有无头浏览器依赖，因此输出是确定性且可复现的。

安装

composer require nextpdf/pro:^3

概念概述

Chart 模块提供三种原生图表渲染器。每一种都是自包含的绘图原语：它在你提供的固定矩形框内渲染，没有回流、不感知容器，也不进行布局协商。你负责放置矩形框；渲染器负责将其填满。

柱状图 —— 一种垂直柱状图，柱体颜色、坐标轴颜色、柱间距和标签字号均可配置。
折线图 —— 一种单系列或多系列折线图，可按系列设置颜色、可选数据点标记、可选网格，并可配置线宽。
饼图 —— 一种圆形图表，自动分配调色板、可选百分比标签，并可选图例。

每个渲染器都遵循相同的形态：一个 fromData(...) 工厂方法、链式的 with*() 配置，以及一个返回 PDF 内容流运算符的 render(ChartBox $box): string 调用。输出是确定性的 —— 相同的输入和配置会产生相同的运算符，这让带图表的文档保持可复现，并可安全地签名或归档。

由于渲染器发出的是矢量运算符而非图像，图表在任意缩放下都保持清晰，且不会给文档增加任何栅格负载。

为何采用这种设计

这里的关键决策是发出原生 PDF 矢量运算符，而不是栅格化图像或驱动无头浏览器。该选择让输出具有确定性：相同的数据和配置总是产生逐字节相同的运算符。确定性的运算符让带图表的文档保持可复现，因而可安全地签名或归档。避开外部渲染器还消除了一项进程依赖，因此吞吐量随数据点数量而非浏览器启动开销扩展。每个渲染器都将其运算符包裹在一对 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 文本运算符发出，绝不会对其进行解释。该模块不记录任何图表数据；应用程序必须在制图前清洗敏感标签。

一致性

图表不受任何外部标准约束；输出是按 ISO 32000-2 内容流语义渲染到页面中的 PDF 内容流。本模块没有制式或密码学层面的一致性接口。

发布边界

本页仅记录外部可观测的行为以及受支持的公共 API 接口。内部命名空间路径、辅助类、机制表、运维手册文件名和工单前缀均不在范围之内。