Bagan

Sekilas pandang

NextPDF Pro merender bagan batang, garis, dan lingkaran langsung ke halaman PDF sebagai operator konten vektor. Tidak ada langkah rasterisasi dan tidak ada ketergantungan pada peramban headless, sehingga keluaran bersifat deterministik dan dapat direproduksi.

Pemasangan

composer require nextpdf/pro:^3

Tinjauan konseptual

Modul Chart menyediakan tiga perender bagan native. Masing-masing adalah primitif gambar yang mandiri: ia merender di dalam kotak persegi panjang berukuran tetap yang Anda sediakan, tanpa reflow, tanpa kesadaran kontainer, dan tanpa negosiasi tata letak. Anda menempatkan kotaknya; perender mengisinya.

• Bagan batang — bagan batang vertikal dengan warna batang, warna sumbu, jarak antarbatang, dan ukuran fon label yang dapat dikonfigurasi.
• Bagan garis — bagan garis satu atau banyak seri dengan warna per seri, penanda titik data opsional, kisi opsional, dan lebar garis yang dapat dikonfigurasi.
• Bagan lingkaran — bagan melingkar dengan penetapan palet otomatis, label persentase opsional, dan legenda opsional.

Setiap perender mengikuti bentuk yang sama: sebuah factory fromData(...), konfigurasi fluen with*(), dan pemanggilan render(ChartBox $box): string yang mengembalikan operator content-stream PDF. Keluaran bersifat deterministik — input dan konfigurasi yang identik menghasilkan operator yang identik, sehingga dokumen yang memuat bagan tetap dapat direproduksi serta aman untuk ditandatangani atau diarsipkan.

Karena perender memancarkan operator vektor alih-alih gambar, bagan tetap tajam pada zoom berapa pun dan tidak menambahkan payload raster ke dokumen.

Mengapa dirancang demikian

Keputusan yang menanggung beban adalah memancarkan operator vektor PDF native alih-alih merasterisasi gambar atau menjalankan peramban headless. Pilihan itu membuat keluaran deterministik: data dan konfigurasi yang identik selalu menghasilkan operator yang byte-identik. Operator deterministik menjaga dokumen berbagan tetap dapat direproduksi, dan karenanya aman untuk ditandatangani atau diarsipkan. Menghindari perender eksternal juga menghilangkan satu ketergantungan proses, sehingga throughput menskala sesuai jumlah titik data alih-alih biaya startup peramban. Setiap perender membungkus operatornya dalam pasangan graphics-state q/Q dan tidak pernah melakukan reflow, sehingga ia mengomposisikan secara terprediksi dan murah.

Latar belakang desain: Pembuatan dokumen bervolume tinggi.

Permukaan API

composer require nextpdf/pro:^3

Permukaan publik Chart terdiri atas lima kelas di 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 — persegi panjang penempatan; fromUserSpace() mengonversi persegi panjang ruang-pengguna yang berorigin di kiri-atas ke origin kiri-bawah PDF; inset() untuk padding.
• ChartColor — rgb(), hex(), palette(), ditambah pemancar operator stroke/fill.

Contoh kode — Mulai cepat

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.

Contoh kode — Produksi

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);

Kasus tepi & jebakan

• Data kosong mengembalikan string kosong alih-alih melempar eksepsi, sehingga kumpulan data yang absen merender ketiadaan alih-alih merusak halaman.
• Bagan lingkaran dengan total nol atau negatif mengembalikan string kosong.
• Seri garis dengan satu titik tidak menggambar segmen garis (satu titik tidak memiliki jalur).
• ChartBox dengan dimensi nol tidak merender sesuatu yang bermakna; tentukan ukuran kotak sebelum merender.
• Perender tidak melakukan kliping ke kotak; sediakan kotak yang pas dengan area halaman yang Anda maksudkan.

Performa

Perenderan bersifat satu lintasan dan linear terhadap jumlah titik data. Tidak ada rasterisasi, tidak ada buffer gambar, dan tidak ada proses eksternal. Ukuran string operator yang dipancarkan membatasi biaya memori. Bagan garis multiseri menskala secara linear terhadap total titik di seluruh seri.

Catatan keamanan

Perender bagan hanya mengonsumsi data numerik dan label; ia tidak mengevaluasi atau mengeksekusi input. Perender memancarkan label sebagai operator teks PDF dan tidak pernah menafsirkannya. Modul ini tidak mencatat data bagan; aplikasi harus menyanitasi label sensitif sebelum membuat bagan.

Konformansi

Bagan tidak diatur oleh standar eksternal; keluaran adalah content stream PDF yang dirender ke dalam halaman sesuai semantik content-stream ISO 32000-2. Tidak ada permukaan konformansi simbologi atau kriptografi untuk modul ini.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas pembantu, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Barcode — NextPDF Pro
• Chart deep reference