圖表引擎¶

NextPDF Pro 的 ChartEngine 直接在 PDF 引擎內部渲染向量圖表，無需外部依賴（不需要 Chrome、Puppeteer 或任何 JavaScript 執行環境）。所有圖表以 PDF 原生向量圖形繪製，在任何解析度下都保持完美清晰度。

支援的圖表類型¶

類型	類別	說明
長條圖	`BarChart`	垂直/水平，可堆疊，可分組
折線圖	`LineChart`	單/多數列，可填充面積，平滑曲線
圓餅圖	`PieChart`	可分離切片，環形模式，半徑調整
散佈圖	`ScatterChart`	XY 點分布，可加趨勢線
面積圖	`AreaChart`	折線 + 填充，多數列半透明疊加
複合圖	`ComboChart`	長條 + 折線混合（雙 Y 軸）

快速開始：長條圖¶

use NextPDF\Pro\Charts\ChartEngine;
use NextPDF\Pro\Charts\BarChart;
use NextPDF\Pro\Charts\ChartDataset;
use NextPDF\Pro\Charts\ChartOptions;
use NextPDF\Pro\Document\ProDocument;

$doc = ProDocument::createStandalone();
$doc->addPage();

$chart = BarChart::create(
    ChartOptions::create(
        title: 'Q1–Q4 2025 季度收入比較',
        width: 450.0,
        height: 250.0,
    )
)
->setLabels(['Q1', 'Q2', 'Q3', 'Q4'])
->addDataset(
    ChartDataset::create('2024 年度')
        ->data([9800000, 11200000, 10900000, 13500000])
        ->color('#94A3B8')
)
->addDataset(
    ChartDataset::create('2025 年度')
        ->data([12500000, 14100000, 13800000, 16200000])
        ->color('#1E3A8A')
);

// 渲染圖表至 PDF
$engine = new ChartEngine();
$engine->render($chart, $doc, x: 72.0, y: 200.0);

$doc->save('/output/quarterly-report.pdf');

折線圖¶

use NextPDF\Pro\Charts\LineChart;
use NextPDF\Pro\Charts\ChartDataset;
use NextPDF\Pro\Charts\ChartOptions;
use NextPDF\Pro\Charts\Axis\LinearAxis;

$chart = LineChart::create(
    ChartOptions::create(
        title: '每月活躍用戶趨勢',
        width: 460.0,
        height: 220.0,
        showLegend: true,
        legendPosition: 'bottom',
    )
)
->setXAxis(
    LinearAxis::create()
        ->labels(['一月', '二月', '三月', '四月', '五月', '六月'])
        ->gridLines(true)
)
->setYAxis(
    LinearAxis::create()
        ->min(0)
        ->max(100000)
        ->stepSize(20000)
        ->formatLabel(fn(int $v) => number_format($v / 1000) . 'K')
)
->addDataset(
    ChartDataset::create('付費用戶')
        ->data([15000, 18000, 22000, 26000, 31000, 38000])
        ->color('#D97706')
        ->lineStyle('solid')
        ->pointStyle('circle')
        ->fillArea(true)
        ->fillOpacity(0.15)
)
->addDataset(
    ChartDataset::create('免費用戶')
        ->data([42000, 51000, 58000, 63000, 70000, 78000])
        ->color('#1E3A8A')
        ->lineStyle('dashed')
        ->smoothCurve(true)
);

圓餅圖¶

use NextPDF\Pro\Charts\PieChart;
use NextPDF\Pro\Charts\PieSlice;
use NextPDF\Pro\Charts\ChartOptions;

$chart = PieChart::create(
    ChartOptions::create(
        title: '2025 年度收入來源分布',
        width: 300.0,
        height: 300.0,
        showLegend: true,
        legendPosition: 'right',
    )
)
->setMode('donut')  // 'pie' | 'donut'
->setDonutRadius(0.6)
->addSlice(PieSlice::create('企業授權', value: 4850000, color: '#1E3A8A'))
->addSlice(PieSlice::create('SaaS 訂閱', value: 3200000, color: '#D97706'))
->addSlice(PieSlice::create('技術支援', value: 1100000, color: '#15803D'))
->addSlice(PieSlice::create('培訓服務', value: 650000, color: '#6366F1'))
->addSlice(PieSlice::create('其他', value: 400000, color: '#9CA3AF'))
->setLabelFormat('{label}\n{percentage}%')
->explodeSlice('企業授權', offset: 12.0); // 突出顯示最大切片

複合圖（長條 + 折線）¶

use NextPDF\Pro\Charts\ComboChart;
use NextPDF\Pro\Charts\Axis\LinearAxis;

$chart = ComboChart::create(
    ChartOptions::create(
        title: '收入與毛利率趨勢（2025）',
        width: 460.0,
        height: 240.0,
    )
)
->setLabels(['Q1', 'Q2', 'Q3', 'Q4'])
->addBarDataset(
    ChartDataset::create('收入（百萬元）')
        ->data([12.5, 14.1, 13.8, 16.2])
        ->color('#1E3A8A')
        ->yAxisId('left')
)
->addLineDataset(
    ChartDataset::create('毛利率（%）')
        ->data([34.4, 35.5, 36.2, 37.7])
        ->color('#D97706')
        ->yAxisId('right')
        ->pointStyle('diamond')
)
->setLeftYAxis(LinearAxis::create()->min(0)->max(20)->title('收入（百萬元）'))
->setRightYAxis(LinearAxis::create()->min(30)->max(45)->title('毛利率（%）'));

串流排版整合¶

圖表可直接作為 StreamingLayoutEngine 的內容元素，自動參與分頁決策：

use NextPDF\Pro\FlowLayout\StreamingLayoutEngine;
use NextPDF\Pro\FlowLayout\LayoutOptions;
use NextPDF\Pro\FlowLayout\Content\ChartContent;
use NextPDF\Pro\FlowLayout\Content\Heading;
use NextPDF\Pro\FlowLayout\Content\Paragraph;

$engine = new StreamingLayoutEngine(
    LayoutOptions::create(pageWidth: 595.28, pageHeight: 841.89,
        marginTop: 72.0, marginBottom: 72.0, marginLeft: 72.0, marginRight: 72.0)
);

$engine->add(Heading::create('第三章：財務分析', level: 1));
$engine->add(Paragraph::create('以下圖表展示本年度四個季度的財務表現：'));

// 圖表作為串流元素，若當前頁空間不足會整體移至下頁
$engine->add(
    ChartContent::create($barChart)
        ->caption('圖 3.1：2025 年季度收入比較')
        ->alignment('center')
        ->keepWithCaption(true)   // 確保圖表與說明文字在同一頁
);

$engine->add(Paragraph::create('從圖表可見，Q4 收入較 Q1 成長 29.6%...'));

樣式系統¶

use NextPDF\Pro\Charts\Style\ChartTheme;
use NextPDF\Pro\Charts\Style\FontStyle;
use NextPDF\Pro\Charts\Style\GridStyle;

$theme = ChartTheme::create()
    ->setTitleFont(FontStyle::create(family: 'Helvetica', size: 12.0, bold: true, color: '#111827'))
    ->setAxisFont(FontStyle::create(family: 'Helvetica', size: 9.0, color: '#6B7280'))
    ->setLegendFont(FontStyle::create(family: 'Helvetica', size: 9.0))
    ->setGrid(GridStyle::create(color: '#E5E7EB', lineWidth: 0.5, dashed: true))
    ->setBackground('#FFFFFF')
    ->setPadding(top: 16.0, right: 20.0, bottom: 16.0, left: 20.0)
    ->setColorPalette(['#1E3A8A', '#D97706', '#15803D', '#6366F1', '#E11D48', '#0F766E']);

// 套用主題至所有圖表
ChartEngine::setDefaultTheme($theme);

資料格式化¶

use NextPDF\Pro\Charts\Formatter\NumberFormatter;
use NextPDF\Pro\Charts\Formatter\CurrencyFormatter;
use NextPDF\Pro\Charts\Formatter\PercentageFormatter;

$chart->setValueFormatter(
    CurrencyFormatter::create(
        currency: 'TWD',
        symbol: 'NT$',
        decimals: 0,
        thousandsSeparator: ',',
    )
);

// 自訂格式化函式
$chart->setTooltipFormatter(
    fn(float $value, string $label, int $datasetIndex) =>
        sprintf('%s: NT$%s 百萬', $label, number_format($value / 1_000_000, 1))
);

無障礙支援¶

圖表自動生成替代文字描述，確保 PDF/UA 合規：

$chart->setAccessibilityDescription(
    'Bar chart showing quarterly revenue comparison between 2024 and 2025. '
    . '2025 Q4 achieved the highest revenue at NT$16.2 million, '
    . 'representing a 20% year-over-year growth.'
);

// 也可設定讓引擎自動生成描述
$chart->setAutoGenerateDescription(true);

相關資源¶