Pro phiên bản

Chart

Tổng quan nhanh

NextPDF Pro kết xuất biểu đồ cột, đường và tròn trực tiếp vào một trang PDF dưới dạng các toán tử nội dung vector. Không có bước rasterize và không phụ thuộc vào trình duyệt headless, nên kết quả là tất định và có thể tái lập.

Cài đặt

composer require nextpdf/pro:^3

Tổng quan khái niệm

Module Chart cung cấp ba bộ kết xuất biểu đồ gốc. Mỗi bộ là một nguyên thủy vẽ khép kín: nó kết xuất bên trong một hộp chữ nhật cố định mà bạn cung cấp, không reflow, không nhận biết container và không thương lượng bố cục. Bạn đặt vị trí cho hộp; bộ kết xuất sẽ lấp đầy nó.

Biểu đồ cột — một biểu đồ cột dọc với màu cột, màu trục, khoảng cách giữa các cột và cỡ phông nhãn có thể cấu hình.
Biểu đồ đường — một biểu đồ đường đơn hoặc nhiều chuỗi với màu theo từng chuỗi, các điểm đánh dấu dữ liệu tùy chọn, lưới tùy chọn và độ rộng đường có thể cấu hình.
Biểu đồ tròn — một biểu đồ tròn với việc gán bảng màu tự động, nhãn phần trăm tùy chọn và chú giải tùy chọn.

Mọi bộ kết xuất đều theo cùng một hình dạng: một factory fromData(...), cấu hình theo kiểu fluent with*(), và một lời gọi render(ChartBox $box): string trả về các toán tử content-stream của PDF. Kết quả là tất định — cùng đầu vào và cấu hình sẽ tạo ra cùng các toán tử, nhờ đó các tài liệu có biểu đồ vẫn có thể tái lập và an toàn để ký hoặc lưu trữ.

Vì các bộ kết xuất phát ra toán tử vector thay vì hình ảnh, biểu đồ vẫn sắc nét ở mọi mức thu phóng và không thêm tải trọng raster nào vào tài liệu.

Vì sao nó hoạt động theo cách này

Quyết định cốt lõi là phát ra các toán tử vector PDF gốc thay vì rasterize một hình ảnh hoặc điều khiển một trình duyệt headless. Lựa chọn đó làm cho kết quả tất định: cùng dữ liệu và cấu hình luôn tạo ra các toán tử giống hệt nhau đến từng byte. Các toán tử tất định giữ cho tài liệu có biểu đồ có thể tái lập, và do đó an toàn để ký hoặc lưu trữ. Việc tránh một bộ kết xuất ngoài cũng loại bỏ một phụ thuộc tiến trình, nên thông lượng mở rộng theo số điểm dữ liệu thay vì chi phí khởi động trình duyệt. Mỗi bộ kết xuất bọc các toán tử của nó trong một cặp trạng thái đồ họa q/Q và không bao giờ reflow, nên nó kết hợp một cách dự đoán được và rẻ.

Bối cảnh thiết kế: Tạo tài liệu khối lượng lớn.

Bề mặt API

composer require nextpdf/pro:^3

Bề mặt công khai của Chart gồm năm lớp trong 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 — hình chữ nhật đặt vị trí; fromUserSpace() chuyển một hình chữ nhật user-space gốc trên-trái sang gốc dưới-trái của PDF; inset() để tạo lề.
ChartColor — rgb(), hex(), palette(), cùng các bộ phát toán tử stroke/fill.

Mẫu mã — Khởi đầu nhanh

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.

Mẫu mã — Production

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

Trường hợp biên & lưu ý

Dữ liệu rỗng trả về một chuỗi rỗng thay vì ném ngoại lệ, nên một tập dữ liệu vắng mặt sẽ không kết xuất gì thay vì làm hỏng trang.
Một biểu đồ tròn có tổng bằng không hoặc âm sẽ trả về một chuỗi rỗng.
Một chuỗi đường chỉ có một điểm sẽ không vẽ đoạn đường nào (một điểm đơn không có đường dẫn).
Một ChartBox có kích thước bằng không sẽ không kết xuất gì có ý nghĩa; hãy định kích thước cho hộp trước khi kết xuất.
Các bộ kết xuất không cắt theo hộp; hãy cung cấp một hộp vừa với vùng trang mà bạn dự định.

Hiệu năng

Việc kết xuất chạy một lượt và tuyến tính theo số điểm dữ liệu. Không có bước rasterize, không có vùng đệm hình ảnh và không có tiến trình ngoài. Kích thước của chuỗi toán tử được phát ra giới hạn chi phí bộ nhớ. Các biểu đồ đường nhiều chuỗi mở rộng tuyến tính theo tổng số điểm trên các chuỗi.

Ghi chú về bảo mật

Các bộ kết xuất biểu đồ chỉ tiêu thụ dữ liệu số và nhãn; chúng không đánh giá hay thực thi đầu vào. Các bộ kết xuất phát ra nhãn dưới dạng toán tử văn bản PDF và không bao giờ diễn giải chúng. Module không ghi log dữ liệu biểu đồ nào; ứng dụng phải làm sạch các nhãn nhạy cảm trước khi vẽ biểu đồ.

Sự phù hợp tiêu chuẩn

Biểu đồ không bị chi phối bởi một tiêu chuẩn bên ngoài; kết quả là một content stream của PDF được kết xuất vào trang theo ngữ nghĩa content-stream của ISO 32000-2. Không có bề mặt phù hợp về bộ ký hiệu hay mật mã cho module này.

Ranh giới công bố

Trang này chỉ ghi lại hành vi quan sát được từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook và tiền tố ticket nằm ngoài phạm vi.