Pro 版本

圖表 — 深入參考

一覽

本頁是 NextPDF Pro Chart 模組的合約層級參考。其介面是 NextPDF\Pro\Chart 中的五個公開類別：BarChart、LineChart 與 PieChart 彩現器、ChartBox 放置矩形，以及 ChartColor 值物件。每個彩現器都是一個繪圖原語。一個靜態工廠會建立它，流暢式的 with*() 呼叫會設定它，而 render(ChartBox $box): string 會回傳所給矩形的 PDF 內容串流運算子。輸出僅為向量且具確定性：相同的輸入與組態會產生相同的位元組。退化的輸入會回傳空字串而非拋出例外，因此 chart 絕不會破壞其周圍的頁面。以任務為導向的視角請見能力頁面。

可用性與授權

此能力隨附於 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`	不會拋出	唯一的建構路徑；建構子為 private
`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`	無序列的 chart	`self`	不會拋出	建構子為 private
`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`	不會拋出	標記以 Bezier 近似的圓形繪製
`LineChart::withGrid()`	`bool $show`	水平四分位格線；預設開啟	`self`	不會拋出	—
`LineChart::render()`	`ChartBox $box`	格線、軸、每序列一條路徑、標籤	`string` 運算子	不會拋出；無序列回傳 `''`	少於兩點的序列不會畫出路徑
`PieChart::fromData()`	`list<string> $labels`、`list<int\|float> $values`	依數值總和計算比例	`self`	不會拋出	建構子為 private
`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 度的 Bezier 區段
`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() 會讀取組態而不變動它，因此一個已設定的彩現器可以彩現到多個框中。每次彩現都會將其輸出包覆在一對儲存/還原圖形狀態之中，因此 chart 狀態絕不會洩漏到頁面。座標以兩位小數發出，色彩分量以三位小數發出，這讓輸出保持位元組穩定。文字透過 /ChartFont 字型資源名稱以所設定的大小彩現；呼叫端須在目標頁面的資源字典中以該名稱註冊一個字型。標籤字串在進入字串運算元之前，會逸出反斜線與括號。彩現器不執行任何重排、任何裁切，也不進行任何容器協商：放置由呼叫端負責。

縮放與版面

長條圖與折線圖會在框內保留固定的繪圖內縮：左 40 點、下 20、右 10、上 10。剩餘的繪圖區域會將值對序列最大值做線性縮放。零或以下的最大值改為對 1.0 縮放，因此全零資料會以平坦內容彩現軸線，而非除以零。兩者都以 0.5 點寬度繪製 X 與 Y 軸，並在四分位位置繪製五個數值刻度。長條圖在超過一千與一百萬時，以 K 與 M 後綴格式化刻度值；折線圖印出純數字。

長條圖

每個值在繪圖寬度上佔據一個相等的槽。長條填滿該槽減去所設定的間距比例，並在槽中置中。類別標籤繪製於繪圖區域下方 12 點處。

折線圖

格線在啟用時，會於軸線與序列下方以淺灰色（0.85 0.85 0.85 RG）繪製四條水平四分位線。每個序列會繪製一條穿過其各點的折線，跨越整個繪圖寬度。選用的標記會在每個資料點以四段式 Bezier 圓形繪製。序列色彩預設為依插入順序連續取用的調色盤項目。

圓餅圖

扇形依資料順序排列，從正 X 軸開始並逆時針掃掠。每條扇形路徑閉合，並以合併的填色與描邊（h B）繪製；弧線切分為至多 90 度的 Bezier 區段。百分比標籤四捨五入至整數百分比，且僅在掃掠超過 15 度的扇形上彩現。圖例在啟用時，會在右側保留 80 點的框寬，並以 12 點行高為每個項目彩現一個 8 點的色塊。半徑為剩餘寬度與框高中較小者的一半，再減去 10 點的邊距。

放置與色彩值物件

ChartBox 是一個以 PDF 使用者單位（點）表示、以左下為原點的不可變矩形。ChartBox::fromUserSpace() 會針對所給的頁面高度翻轉，將左上原點矩形轉換過來。inset() 會回傳一個新的、較小的框；right() 與 top() 是存取器方法。ChartColor 自成一體，不依賴 Core 色彩類別。當呼叫端未提供時，其 12 項調色盤會指派序列與扇形色彩。

支援矩陣（以證據支撐）

一個圖表類型或功能只有在一個 pro/tests/** fixture 演練它時才能取得 Verified。沒有任何外部標準治理圖表，因此證據是單元層級的行為覆蓋。

圖表類型/功能	狀態	證據（測試路徑）	信心	註記
長條圖 — 彩現、軸、長條矩形、間距箝制、空/全零資料、K/M 數值格式化	Verified	`pro/tests/Unit/Chart/BarChartTest.php`; `BarChartArithmeticCoverageTest.php`; `BarChartBoundaryCoverageTest.php`	高	已斷言圖形狀態包覆、軸線、長條高度比例、刻度數量與格式化邊界。
折線圖 — 單一與多序列、線段路徑、軸、圓點、格線、單點	Verified	`pro/tests/Unit/Chart/LineChartTest.php`; `LineChartCoverageTest.php`; `LineChartArithmeticCoverageTest.php`; `LineChartTypeCastCoverageTest.php`	高	涵蓋多序列、單點不畫線、空序列、格線與圓點路徑。
圓餅圖 — 扇形、Bezier 分段、百分比、圖例、零/負總和	Verified	`pro/tests/Unit/Chart/PieChartTest.php`; `PieChartArithmeticCoverageTest.php`; `PieChartBoundaryCoverageTest.php`	高	涵蓋扇形路徑、每次掃掠的區段數、15 度標籤門檻、圖例幾何，以及空字串行為。
`ChartBox` — 座標轉換（使用者空間至 PDF）、頁面頂端/底端、零維度、內縮	Verified	`pro/tests/Unit/Chart/ChartBoxTest.php`	高	在頁面頂端、底端與零維度邊界處，將左上原點轉換為左下原點。
`ChartColor` — RGB 縮放、十六進位解析、調色盤、描邊/填色運算子	Verified	`pro/tests/Unit/Chart/ChartColorTest.php`	高	0–255 至 0–1 縮放、帶 `#` 前綴與裸十六進位、大小寫混用、超過 12 項後的調色盤環繞。
跨彩現器回歸強化	Verified	`pro/tests/Unit/Chart/ChartCoverageTest.php`	高	橫跨三個彩現器的共用回歸測試套件，外加數值格式化算術。
超出長條圖/折線圖/圓餅圖的圖表類型（area、scatter、stacked、donut 等）	Not supported	—	高	沒有隨附任何彩現器。模組介面恰好就是長條圖、折線圖、圓餅圖。誠實陳述：這並非「每一種圖表類型」。

誠實計數：Verified 6 列、Claimed 0、Not supported 1（除長條圖、折線圖、圓餅圖以外的任何圖表類型）。

邊界案例與失效模式

沒有任何彩現器會因資料而拋出。退化的輸入會降級為空字串：空的長條或折線資料、空的序列清單，以及小於等於零的圓餅總和，全都回傳 ''。
少於兩點的折線序列不會畫出路徑也不會畫出標記；軸與標籤仍會彩現。
負的長條值不會被拒絕；長條矩形會延伸到 X 軸下方。
標籤與數值的數量不會交叉驗證。呼叫端須提供長度相符的清單。
維度為零或負的 ChartBox 會被接受並產生退化的輸出；呼叫端必須為框設定尺寸。
彩現器不裁切。過大的 chart、其繪圖區下方的類別標籤，或過長的圖例，都可能溢出預期的頁面區域。
若頁面在 chart 字型資源名稱下缺少字型，文字運算子將指向一個未定義的資源；此時檢視器的行為未定義。
ChartColor::hex() 不執行任何驗證；短於六位的輸入會將缺少的分量解碼為零。ChartColor::palette() 在負索引時會以 TypeError 失敗，因為 PHP 的負模數無法解析出任何調色盤鍵。
此模組不執行任何密碼學；FIPS 模式沒有 chart 專屬的行為。

一致性

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 穩定，並可安全地簽署或封存。
在每個承載 chart 的頁面上，以 chart 字型資源名稱註冊一次字型。
可自由地在多個框之間重用一個已設定的彩現器；render() 不執行任何狀態變動。
測試證據位於 pro/tests/Unit/Chart/ 之下；支援矩陣將每個 Verified 列錨定到其測試套件。

發佈邊界

本頁僅記載外部可觀察的行為，以及受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表、runbook 檔名與工單前綴皆不在範圍內。

另請參閱

Chart（能力） — 以任務為導向的概觀、安裝與程式碼範例。
Barcode — 深度參考 — 姊妹級的 Pro 繪圖介面，具備其自身以證據支撐的支援矩陣。