Pro 版本

Chart — 深度参考

概览

本页面是 NextPDF Pro Chart 模块的契约级参考。其接口面是 NextPDF\Pro\Chart 中的五个公共类：BarChart、LineChart 与 PieChart 渲染器、ChartBox 放置矩形，以及 ChartColor 值对象。每个渲染器都是一个绘图原语。一个静态工厂创建它，流畅的 with*() 调用配置它，而 render(ChartBox $box): string 返回针对所提供矩形的 PDF 内容流运算符。输出仅为矢量且是确定性的：相同的输入与配置产生相同的字节。退化输入返回空字符串而非抛出异常，因此一个图表绝不会破坏其所在的页面。面向任务的视角见能力页面。

可用性与授权

该能力随 NextPDF Pro（nextpdf/pro）发行，并通过 Pro 级授权信封激活。缺少该权益的部署不会加载此能力的类。比较版本并获取授权。

Chart 渲染器在 chart.* 能力家族下受能力授权约束。当该能力未获授权时，Chart 渲染器不可用。

公共 API 接口面

composer require nextpdf/pro:^3

符号	参数	默认行为	返回	抛出或失败于	备注
`BarChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	值被转换为 float	`self`	不抛出	唯一的构造路径；构造函数为私有
`BarChart::withBarColor()`	`ChartColor $color`	柱体填充；默认为调色板条目 0	`self`	不抛出	流畅；改变接收者
`BarChart::withAxisColor()`	`ChartColor $color`	坐标轴描边；默认 `#333333`	`self`	不抛出	—
`BarChart::withBarGap()`	`float $gap`	间隙占槽位宽度的比例；默认 `0.2`	`self`	不抛出	钳制到 `0.0`–`0.9`；越界输入被钳制而非拒绝
`BarChart::withFontSize()`	`float $size`	标签字号（点）；默认 `7.0`	`self`	不抛出	—
`BarChart::render()`	`ChartBox $box`	坐标轴、柱体、类别标签、五个数值刻度	`string` 运算符	不抛出；空数据返回 `''`	非正的最大值以 `1.0` 为标度
`LineChart::create()`	`list<string> $labels`	不含系列的图表	`self`	不抛出	构造函数为私有
`LineChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	添加一个未命名系列	`self`	不抛出	单系列便捷方法
`LineChart::addSeries()`	`string $name`, `list<int\|float> $values`, `?ChartColor $color = null`	`null` 颜色按系列索引从调色板自动分配	`self`	不抛出	系列名称保留用于图例
`LineChart::withAxisColor()`	`ChartColor $color`	坐标轴描边；默认 `#333333`	`self`	不抛出	—
`LineChart::withLineWidth()`	`float $width`	系列描边宽度；默认 `1.5`	`self`	不抛出	—
`LineChart::withFontSize()`	`float $size`	标签字号；默认 `7.0`	`self`	不抛出	—
`LineChart::withDots()`	`bool $show`, `float $radius = 2.5`	数据点标记；默认开启	`self`	不抛出	标记绘制为贝塞尔近似圆
`LineChart::withGrid()`	`bool $show`	水平四分位网格；默认开启	`self`	不抛出	—
`LineChart::render()`	`ChartBox $box`	网格、坐标轴、每系列一条路径、标签	`string` 运算符	不抛出；无系列返回 `''`	少于两个点的系列不绘制路径
`PieChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	比例由数值总和计算	`self`	不抛出	构造函数为私有
`PieChart::withColors()`	`list<ChartColor> $colors`	每个扇区一种颜色，按顺序	`self`	不抛出	缺失的条目回退到调色板
`PieChart::withStrokeColor()`	`ChartColor $color`	扇区轮廓；默认白色	`self`	不抛出	—
`PieChart::withFontSize()`	`float $size`	标签字号；默认 `7.0`	`self`	不抛出	—
`PieChart::withPercentages()`	`bool $show`	百分比标签；默认开启	`self`	不抛出	仅在扫掠超过 15 度的扇区上渲染标签
`PieChart::withLegend()`	`bool $show`	右侧图例；默认开启	`self`	不抛出	图例预留 80 点的矩形框宽度
`PieChart::render()`	`ChartBox $box`	扇区、可选标签、可选图例	`string` 运算符	不抛出；空数据或总和小于等于零返回 `''`	弧被拆分为至多 90 度的贝塞尔段
`ChartBox::__construct()`	`float $x`, `float $y`, `float $width`, `float $height`	PDF 左下角原点，单位为点	—	不抛出	`final readonly`；尺寸不做校验
`ChartBox::fromUserSpace()`	`float $x`, `float $y`, `float $width`, `float $height`, `float $pageHeight`	将左上角原点矩形翻转到 PDF 坐标	`self`	不抛出	—
`ChartBox::right()`	无	`x + width`	`float`	不抛出	方法，而非属性
`ChartBox::top()`	无	`y + height`	`float`	不抛出	方法，而非属性
`ChartBox::inset()`	`float $left`, `float $bottom`, `float $right`, `float $top`	按给定内缩量收缩的子矩形框	`self`	不抛出	过大的内缩量产生负尺寸；不做校验
`ChartColor::__construct()`	`float $r`, `float $g`, `float $b`，各为 `0.0`–`1.0`	—	—	不抛出	`final readonly`；分量不做钳制
`ChartColor::rgb()`	`int $r`, `int $g`, `int $b`，各为 `0`–`255`	将分量缩放到 `0.0`–`1.0`	`self`	不抛出	—
`ChartColor::hex()`	`string $hex`	接受带 `#` 前缀或裸的六位十六进制	`self`	不抛出	缺失的末尾数字解码为零
`ChartColor::palette()`	`int $index`	内置 12 色调色板	`self`	负索引时抛出 `TypeError`	非负索引以 12 取模回绕
`ChartColor::strokeOperator()`	无	描边颜色运算符（`RG`），三位小数	`string`	不抛出	方法，而非属性
`ChartColor::fillOperator()`	无	填充颜色运算符（`rg`），三位小数	`string`	不抛出	方法，而非属性

入口点签名

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

行为契约

共通渲染器形态

三个渲染器都遵循同一生命周期：一个静态工厂、流畅配置、一次 render() 调用。配置方法改变接收者并返回它；渲染器不是不可变值对象。render() 读取配置而不改变它，因此一个已配置的渲染器可以渲染到多个矩形框中。每次渲染都将其输出包裹在一对保存/恢复图形状态之间，因此图表状态绝不会泄漏到页面中。坐标以两位小数发出，颜色分量以三位小数发出，从而保持输出字节稳定。文本通过 /ChartFont 字体资源名以所配置的字号渲染；调用方需在目标页面的资源字典中以该名称注册一个字体。标签字符串在进入字符串操作数之前会对反斜杠与圆括号进行转义。渲染器不执行回流、不裁剪，也不进行容器协商：放置由调用方负责。

缩放与布局

柱状图与折线图在矩形框内预留固定的绘图内缩：左 40 点、下 20 点、右 10 点、上 10 点。其余的绘图区域将数值相对于系列最大值线性缩放。最大值为零或更小时改以 1.0 为标度，因此全零数据渲染出的坐标轴内容平坦而非除以零。两者都以 0.5 点宽度绘制 X 与 Y 轴，并在四分位位置绘制五个数值刻度。柱状图在超过一千与一百万时以 K 和 M 后缀格式化刻度值；折线图打印纯数字。

柱状图

每个值在绘图宽度上占据一个等宽槽位。柱体填充槽位减去所配置的间隙比例后的部分，并在槽位中居中。类别标签绘制在绘图区域下方 12 点处。

折线图

网格在启用时，于坐标轴与系列下方以浅灰（0.85 0.85 0.85 RG）绘制四条水平四分位线。每个系列穿过其各点绘制一条折线，横跨整个绘图宽度。可选的标记在每个数据点绘制为四段贝塞尔圆。系列颜色默认按插入顺序取连续的调色板条目。

饼图

扇区按数据顺序布局，从正 X 轴开始逆时针扫掠。每条扇区路径闭合并以填充加描边组合（h B）绘制；弧被拆分为至多 90 度的贝塞尔段。百分比标签四舍五入到整数百分比，且仅在扫掠超过 15 度的扇区上渲染。图例在启用时于右侧预留 80 点的矩形框宽度，并以 12 点行高为每个条目渲染一个 8 点色块。半径为剩余宽度与矩形框高度中较小者的一半，再减去 10 点边距。

放置与颜色值对象

ChartBox 是一个以 PDF 用户单位（点）表示、以左下角为原点的不可变矩形。ChartBox::fromUserSpace() 通过相对所提供的页面高度翻转来转换左上角原点矩形。inset() 返回一个新的、更小的矩形框；right() 与 top() 是访问器方法。ChartColor 是自包含的，不依赖 Core 颜色类。当调用方未提供颜色时，其 12 条目调色板为系列与扇区分配颜色。

支持矩阵（以佐证支撑）

一个图表类型或功能只有当一个 pro/tests/** fixture 演练它时才获评 已验证。没有外部标准管辖图表，因此佐证是单元级的行为覆盖。

图表类型 / 功能	状态	佐证（测试路径）	置信度	备注
柱状图 —— 渲染、坐标轴、柱体矩形、间隙钳制、空/全零数据、K/M 数值格式化	已验证	`pro/tests/Unit/Chart/BarChartTest.php`; `BarChartArithmeticCoverageTest.php`; `BarChartBoundaryCoverageTest.php`	high	断言了图形状态包裹、坐标轴线、柱高比例、刻度数量与格式化边界。
折线图 —— 单系列与多系列、折线路径、坐标轴、数据点、网格、单点	已验证	`pro/tests/Unit/Chart/LineChartTest.php`; `LineChartCoverageTest.php`; `LineChartArithmeticCoverageTest.php`; `LineChartTypeCastCoverageTest.php`	high	覆盖了多系列、单点不绘线、空系列、网格与数据点路径。
饼图 —— 扇区、贝塞尔分段、百分比、图例、零/负总和	已验证	`pro/tests/Unit/Chart/PieChartTest.php`; `PieChartArithmeticCoverageTest.php`; `PieChartBoundaryCoverageTest.php`	high	覆盖了扇区路径、每次扫掠的分段数量、15 度标签阈值、图例几何与空字符串行为。
`ChartBox` —— 坐标转换（用户空间到 PDF）、页面 top/bottom、零尺寸、inset	已验证	`pro/tests/Unit/Chart/ChartBoxTest.php`	high	在页面 top、bottom 及零尺寸边界处的左上角原点到左下角原点转换。
`ChartColor` —— RGB 缩放、十六进制解析、调色板、描边/填充运算符	已验证	`pro/tests/Unit/Chart/ChartColorTest.php`	high	0–255 到 0–1 缩放、带 `#` 前缀与裸十六进制、混合大小写、12 条目后的调色板回绕。
跨渲染器回归加固	已验证	`pro/tests/Unit/Chart/ChartCoverageTest.php`	high	三个渲染器之间共享的回归套件，外加数值格式化算术。
柱/折/饼之外的图表类型（面积图、散点图、堆叠图、环形图等）	不支持	—	high	无渲染器发行。模块接口面恰好就是柱、折、饼。诚实陈述：这并非“每一种图表类型”。

诚实计数：已验证 6 行，声明 0，不支持 1（柱、折、饼之外的任何图表类型）。

边界情形与失败模式

没有渲染器会因数据而抛出异常。退化输入退化为空字符串：空的柱状或折线数据、空的系列列表，以及小于等于零的饼图总和都返回 ''。
少于两个点的折线系列不绘制路径也不绘制标记；坐标轴与标签仍会渲染。
负的柱状值不会被拒绝；柱体矩形会延伸到 X 轴下方。
标签数量与数值数量不做交叉校验。调用方需提供长度匹配的列表。
尺寸为零或为负的 ChartBox 会被接受并产出退化输出；调用方必须为矩形框设置尺寸。
渲染器不裁剪。一个过大的图表、其绘图区下方的类别标签，或一个较长的图例都可能溢出预期的页面区域。
若页面在图表字体资源名下缺少字体，文本运算符将引用一个未定义的资源；此时查看器行为是未定义的。
ChartColor::hex() 不做校验；短于六位的输入将缺失的分量解码为零。ChartColor::palette() 在负索引时以 TypeError 失败，因为 PHP 的负取模无法解析出调色板键。
该模块不执行任何密码学；FIPS 模式没有图表专属行为。

符合性

Chart 模块发出 PDF 内容流运算符。没有外部图表、符号系统或密码学标准管辖其输出，因此唯一的符合性接口面是所发出的运算符流。

主张	标准	条款
所发出的图形遵循内容流运算符模型；输出嵌套于一个保存并恢复的图形状态之内。	ISO 32000-2	§8.1
柱体、折线、扇区与标记都是路径对象：构造以 `m` 或 `re` 开始，并以一个路径绘制运算符结束。	ISO 32000-2	§8.5.2
标签渲染为文本对象：位置在 `BT` 之后确立，字形以 `Tj` 文本显示运算符绘制。	ISO 32000-2	§9.2.2, §9.4.3

所有条款均为转述；本页面不复现任何规范性原文。这些是能力陈述，而非认证；NextPDF 不持有任何认证，也不授予任何认证。运算符流的正确渲染还取决于所在文档格式良好，而这是文档编写者的责任。

开发说明

全部五个类都带有 @since 1.9.0，并在 nextpdf/pro 3.1.0 中为当前版本。
该模块是自包含的：渲染器仅依赖 ChartBox 与 ChartColor，不与 Core 耦合。
确定性输出使含图表的文档可复现、diff 稳定，并可安全地签名或归档。
在每个承载图表的页面上，以图表字体资源名注册一次字体。
可自由地在多个矩形框间复用一个已配置的渲染器；render() 不执行任何状态改变。
测试佐证位于 pro/tests/Unit/Chart/；支持矩阵将每个已验证行锚定到其套件。

发布边界

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

另请参阅

Chart（能力） —— 面向任务的概览、安装与代码示例。
Barcode — 深度参考 —— 拥有自己以佐证支撑的支持矩阵的姊妹 Pro 绘图接口面。