Pro 版本

圖表

速覽

NextPDF Pro 會將長條圖、折線圖與圓餅圖直接以向量內容運算子的形式繪製到 PDF 頁面中。過程沒有點陣化步驟，也不依賴無頭瀏覽器，因此輸出具有決定性且可重現。

安裝

composer require nextpdf/pro:^3

概念總覽

Chart 模組提供三種原生圖表繪製器。每一種都是自包含的繪圖原語：它會在你提供的固定矩形框內繪製，不會重新排版、不感知容器，也不進行任何排版協商。框由你定位；繪製器負責填滿它。

長條圖（Bar chart） —— 一種垂直長條圖，可設定長條顏色、座標軸顏色、長條間距與標籤字級。
折線圖（Line chart） —— 一種單系列或多系列折線圖，可逐系列設定顏色、選用的資料點標記、選用的格線，以及可設定的線寬。
圓餅圖（Pie 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 不會繪製任何有意義的內容；請在繪製前先設定框的大小。
繪製器不會裁切到框邊界；請提供能容納你預期頁面區域的框。

效能

繪製為單趟（single-pass），且時間與資料點數量呈線性關係。過程沒有點陣化、沒有影像緩衝區，也沒有外部行程。發出的運算子字串大小即為記憶體成本的上界。多系列折線圖的成本與各系列資料點總數呈線性關係。

安全注意事項

圖表繪製器只消費數值與標籤資料；它們不會對輸入進行求值或執行。繪製器會將標籤輸出為 PDF 文字運算子，並且絕不解讀它們。本模組不記錄任何圖表資料；應用程式必須在繪製前先清理敏感標籤。

一致性

圖表不受任何外部標準規範；輸出是依 ISO 32000-2 內容流語意繪製到頁面中的一段 PDF 內容流。本模組沒有任何符號系統或密碼學的一致性面向。

發佈邊界

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