Pro phiên bản

Chart — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này là tài liệu tham chiếu ở mức hợp đồng cho module NextPDF Pro Chart. Bề mặt gồm năm lớp công khai trong NextPDF\Pro\Chart: các renderer BarChart, LineChart và PieChart, hình chữ nhật đặt chỗ ChartBox, và value object ChartColor. Mỗi renderer là một drawing primitive. Một static factory tạo ra nó, các lời gọi with*() kiểu fluent cấu hình nó, và render(ChartBox $box): string trả về các toán tử content-stream PDF cho hình chữ nhật được cung cấp. Đầu ra chỉ là vector và tất định: đầu vào và cấu hình giống nhau tạo ra các byte giống nhau. Các đầu vào suy biến trả về một chuỗi rỗng thay vì ném lỗi, nên một biểu đồ không bao giờ làm hỏng trang xung quanh. Góc nhìn theo hướng tác vụ nằm ở trang năng lực.

Tính khả dụng & cấp phép

Năng lực này đi kèm trong NextPDF Pro (nextpdf/pro) và kích hoạt với một license envelope bậc Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và lấy giấy phép.

Các renderer biểu đồ được cấp phép theo năng lực dưới họ năng lực chart.*. Khi năng lực chưa được cấp phép, các renderer biểu đồ không khả dụng.

Bề mặt Public API

composer require nextpdf/pro:^3

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném lỗi hoặc thất bại với	Ghi chú
`BarChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Các giá trị được ép sang float	`self`	Không ném lỗi	Đường tạo dựng duy nhất; constructor là private
`BarChart::withBarColor()`	`ChartColor $color`	Tô cột; mặc định là mục palette 0	`self`	Không ném lỗi	Fluent; thay đổi đối tượng nhận
`BarChart::withAxisColor()`	`ChartColor $color`	Nét trục; mặc định `#333333`	`self`	Không ném lỗi	—
`BarChart::withBarGap()`	`float $gap`	Khoảng cách theo tỷ lệ của chiều rộng slot; mặc định `0.2`	`self`	Không ném lỗi	Được kẹp về `0.0`–`0.9`; đầu vào ngoài khoảng bị kẹp, không bị từ chối
`BarChart::withFontSize()`	`float $size`	Cỡ chữ nhãn tính theo point; mặc định `7.0`	`self`	Không ném lỗi	—
`BarChart::render()`	`ChartBox $box`	Trục, cột, nhãn danh mục, năm vạch giá trị	toán tử `string`	Không ném lỗi; dữ liệu rỗng trả về `''`	Giá trị lớn nhất không dương được co giãn theo `1.0`
`LineChart::create()`	`list<string> $labels`	Biểu đồ không có chuỗi	`self`	Không ném lỗi	Constructor là private
`LineChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Thêm một chuỗi không tên	`self`	Không ném lỗi	Tiện ích một-chuỗi
`LineChart::addSeries()`	`string $name`, `list<int\|float> $values`, `?ChartColor $color = null`	Màu `null` tự gán từ palette theo chỉ số chuỗi	`self`	Không ném lỗi	Tên chuỗi được dành cho việc dùng trong chú giải
`LineChart::withAxisColor()`	`ChartColor $color`	Nét trục; mặc định `#333333`	`self`	Không ném lỗi	—
`LineChart::withLineWidth()`	`float $width`	Độ rộng nét chuỗi; mặc định `1.5`	`self`	Không ném lỗi	—
`LineChart::withFontSize()`	`float $size`	Cỡ chữ nhãn; mặc định `7.0`	`self`	Không ném lỗi	—
`LineChart::withDots()`	`bool $show`, `float $radius = 2.5`	Điểm đánh dấu dữ liệu; bật mặc định	`self`	Không ném lỗi	Điểm đánh dấu được vẽ dưới dạng hình tròn xấp xỉ bằng Bezier
`LineChart::withGrid()`	`bool $show`	Lưới tứ phân vị ngang; bật mặc định	`self`	Không ném lỗi	—
`LineChart::render()`	`ChartBox $box`	Lưới, trục, một đường dẫn mỗi chuỗi, nhãn	toán tử `string`	Không ném lỗi; không có chuỗi thì trả về `''`	Một chuỗi ngắn hơn hai điểm không vẽ đường dẫn nào
`PieChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Tỷ lệ được tính từ tổng các giá trị	`self`	Không ném lỗi	Constructor là private
`PieChart::withColors()`	`list<ChartColor> $colors`	Một màu mỗi lát, theo thứ tự	`self`	Không ném lỗi	Các mục thiếu quay về dùng palette
`PieChart::withStrokeColor()`	`ChartColor $color`	Viền lát; mặc định trắng	`self`	Không ném lỗi	—
`PieChart::withFontSize()`	`float $size`	Cỡ chữ nhãn; mặc định `7.0`	`self`	Không ném lỗi	—
`PieChart::withPercentages()`	`bool $show`	Nhãn phần trăm; bật mặc định	`self`	Không ném lỗi	Nhãn chỉ hiển thị trên các lát quét quá 15 độ
`PieChart::withLegend()`	`bool $show`	Chú giải bên phải; bật mặc định	`self`	Không ném lỗi	Chú giải dành 80 point chiều rộng hộp
`PieChart::render()`	`ChartBox $box`	Các sector, nhãn tùy chọn, chú giải tùy chọn	toán tử `string`	Không ném lỗi; dữ liệu rỗng hoặc tổng bằng hoặc dưới không thì trả về `''`	Các cung được chia thành các đoạn Bezier tối đa 90 độ
`ChartBox::__construct()`	`float $x`, `float $y`, `float $width`, `float $height`	Gốc dưới-trái PDF, tính theo point	—	Không ném lỗi	`final readonly`; kích thước không được xác thực
`ChartBox::fromUserSpace()`	`float $x`, `float $y`, `float $width`, `float $height`, `float $pageHeight`	Lật một hình chữ nhật gốc-trên-trái sang tọa độ PDF	`self`	Không ném lỗi	—
`ChartBox::right()`	không có	`x + width`	`float`	Không ném lỗi	Phương thức, không phải thuộc tính
`ChartBox::top()`	không có	`y + height`	`float`	Không ném lỗi	Phương thức, không phải thuộc tính
`ChartBox::inset()`	`float $left`, `float $bottom`, `float $right`, `float $top`	Hộp con thu nhỏ theo các inset đã cho	`self`	Không ném lỗi	Inset quá lớn tạo ra kích thước âm; không được xác thực
`ChartColor::__construct()`	`float $r`, `float $g`, `float $b`, mỗi cái `0.0`–`1.0`	—	—	Không ném lỗi	`final readonly`; các thành phần không được kẹp
`ChartColor::rgb()`	`int $r`, `int $g`, `int $b`, mỗi cái `0`–`255`	Co giãn các thành phần về `0.0`–`1.0`	`self`	Không ném lỗi	—
`ChartColor::hex()`	`string $hex`	Chấp nhận hex sáu chữ số có tiền tố `#` hoặc trần	`self`	Không ném lỗi	Các chữ số cuối bị thiếu được giải mã thành không
`ChartColor::palette()`	`int $index`	Palette 12 màu tích hợp	`self`	`TypeError` khi chỉ số âm	Các chỉ số không âm cuộn theo modulo 12
`ChartColor::strokeOperator()`	không có	Toán tử màu nét (`RG`), ba chữ số thập phân	`string`	Không ném lỗi	Phương thức, không phải thuộc tính
`ChartColor::fillOperator()`	không có	Toán tử màu tô (`rg`), ba chữ số thập phân	`string`	Không ném lỗi	Phương thức, không phải thuộc tính

Chữ ký điểm vào

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

Hợp đồng hành vi

Hình dạng renderer chung

Cả ba renderer đều theo một vòng đời: một static factory, cấu hình fluent, một lời gọi render(). Các phương thức cấu hình thay đổi đối tượng nhận và trả về nó; các renderer không phải là các value object bất biến. render() đọc cấu hình mà không thay đổi nó, nên một renderer đã cấu hình có thể kết xuất vào nhiều hộp. Mỗi lần render bao bọc đầu ra của nó trong một cặp lưu/khôi phục graphics-state, nên trạng thái biểu đồ không bao giờ rò rỉ vào trang. Tọa độ được phát ra với hai chữ số thập phân và các thành phần màu với ba, giữ cho đầu ra ổn định ở mức byte. Văn bản được kết xuất qua tên tài nguyên font /ChartFont ở cỡ đã cấu hình; bên gọi đăng ký một font dưới tên đó trong resource dictionary của trang đích. Các chuỗi nhãn escape dấu gạch chéo ngược và dấu ngoặc đơn trước khi đi vào các toán hạng chuỗi. Các renderer không thực hiện reflow, không clip, và không thương lượng container: bên gọi sở hữu việc đặt chỗ.

Co giãn và bố cục

Biểu đồ cột và đường dành một inset vẽ cố định bên trong hộp: 40 point trái, 20 dưới, 10 phải, 10 trên. Vùng vẽ còn lại co giãn các giá trị tuyến tính theo giá trị lớn nhất của chuỗi. Một giá trị lớn nhất bằng không hoặc nhỏ hơn thì co giãn theo 1.0 thay thế, nên dữ liệu toàn-bằng-không kết xuất các trục với nội dung phẳng thay vì chia cho không. Cả hai đều vẽ trục X và Y ở độ rộng 0.5-point và năm vạch giá trị tại các vị trí tứ phân vị. Biểu đồ cột định dạng các giá trị vạch với hậu tố K và M trên một nghìn và một triệu; biểu đồ đường in các số thuần.

Biểu đồ cột

Mỗi giá trị chiếm một slot bằng nhau trên chiều rộng vẽ. Cột lấp đầy slot trừ đi phần khoảng cách đã cấu hình và được canh giữa trong slot. Nhãn danh mục được vẽ 12 point bên dưới vùng vẽ.

Biểu đồ đường

Lưới, khi được bật, vẽ bốn đường tứ phân vị ngang màu xám nhạt (0.85 0.85 0.85 RG) bên dưới các trục và các chuỗi. Mỗi chuỗi vẽ một polyline qua các điểm của nó, trải hết chiều rộng vẽ. Các điểm đánh dấu tùy chọn được vẽ dưới dạng hình tròn Bezier bốn đoạn tại mỗi điểm dữ liệu. Màu chuỗi mặc định là các mục palette liên tiếp theo thứ tự chèn.

Biểu đồ tròn

Các lát được bố trí theo thứ tự dữ liệu, bắt đầu từ trục X dương và quét ngược chiều kim đồng hồ. Mỗi đường dẫn sector đóng lại và tô với fill và stroke kết hợp (h B); các cung được chia thành các đoạn Bezier tối đa 90 độ. Nhãn phần trăm được làm tròn tới phần trăm nguyên và chỉ hiển thị trên các lát quét quá 15 độ. Chú giải, khi được bật, dành 80 point chiều rộng hộp ở bên phải và kết xuất một ô mẫu 8-point mỗi mục ở chiều cao dòng 12-point. Bán kính là một nửa của giá trị nhỏ hơn giữa chiều rộng còn lại và chiều cao hộp, trừ đi một lề 10-point.

Các value object đặt chỗ và màu

ChartBox là một hình chữ nhật bất biến theo đơn vị người dùng PDF (point) với gốc dưới-trái. ChartBox::fromUserSpace() chuyển đổi một hình chữ nhật gốc-trên-trái bằng cách lật theo chiều cao trang được cung cấp. inset() trả về một hộp mới, nhỏ hơn; right() và top() là các phương thức truy cập. ChartColor khép kín và không phụ thuộc vào các lớp màu của Core. Palette 12 mục của nó gán màu cho chuỗi và lát khi bên gọi không cung cấp màu nào.

Ma trận hỗ trợ (có bằng chứng)

Một loại biểu đồ hoặc tính năng chỉ đạt Verified khi một fixture pro/tests/** thực thi nó. Không có tiêu chuẩn bên ngoài nào chi phối các biểu đồ, nên bằng chứng là độ bao phủ hành vi ở mức unit.

Loại biểu đồ / tính năng	Tình trạng	Bằng chứng (đường dẫn test)	Độ tin cậy	Ghi chú
Bar chart — render, trục, hình chữ nhật cột, kẹp khoảng cách, dữ liệu rỗng/toàn-bằng-không, định dạng giá trị K/M	Verified	`pro/tests/Unit/Chart/BarChartTest.php`; `BarChartArithmeticCoverageTest.php`; `BarChartBoundaryCoverageTest.php`	high	Bọc graphics-state, các đường trục, tỷ lệ chiều-cao-cột, số lượng vạch, và các biên định dạng được khẳng định.
Line chart — đơn và đa chuỗi, đường dẫn line, trục, dots, grid, một-điểm	Verified	`pro/tests/Unit/Chart/LineChartTest.php`; `LineChartCoverageTest.php`; `LineChartArithmeticCoverageTest.php`; `LineChartTypeCastCoverageTest.php`	high	Đa-chuỗi, không-đường khi một điểm, chuỗi-rỗng, các đường dẫn grid và dot được bao phủ.
Pie chart — sectors, phân đoạn Bezier, phần trăm, chú giải, tổng bằng-không/âm	Verified	`pro/tests/Unit/Chart/PieChartTest.php`; `PieChartArithmeticCoverageTest.php`; `PieChartBoundaryCoverageTest.php`	high	Các đường dẫn sector, số lượng đoạn theo mỗi lượt quét, ngưỡng nhãn 15 độ, hình học chú giải, và hành vi chuỗi-rỗng được bao phủ.
`ChartBox` — chuyển đổi tọa độ (user space sang PDF), đỉnh/đáy trang, kích thước bằng không, inset	Verified	`pro/tests/Unit/Chart/ChartBoxTest.php`	high	Chuyển đổi gốc-trên-trái sang gốc-dưới-trái tại đỉnh trang, đáy trang, và các biên kích-thước-bằng-không.
`ChartColor` — co giãn RGB, phân tích hex, palette, toán tử stroke/fill	Verified	`pro/tests/Unit/Chart/ChartColorTest.php`	high	Co giãn 0–255 sang 0–1, hex có tiền tố `#` và hex trần, hoa-thường lẫn lộn, cuộn vòng palette sau 12 mục.
Cross-renderer regression hardening	Verified	`pro/tests/Unit/Chart/ChartCoverageTest.php`	high	Bộ hồi quy dùng chung trên cả ba renderer cộng với số học định dạng giá trị.
Các loại biểu đồ ngoài bar/line/pie (area, scatter, stacked, donut, v.v.)	Not supported	—	high	Không có renderer đi kèm. Bề mặt module đúng là bar, line, pie. Nói thẳng: đây không phải “mọi loại biểu đồ”.

Số đếm trung thực: Verified 6 hàng, Claimed 0, Not supported 1 (bất kỳ loại biểu đồ nào khác ngoài bar, line, pie).

Trường hợp ngoại lệ & các chế độ lỗi

Không renderer nào ném lỗi trên dữ liệu. Đầu vào suy biến hạ xuống thành một chuỗi rỗng: dữ liệu cột hoặc đường rỗng, một danh sách chuỗi rỗng, và một tổng tròn bằng hoặc dưới không đều trả về ''.
Một chuỗi đường có ít hơn hai điểm không vẽ đường dẫn và không có điểm đánh dấu; các trục và nhãn vẫn được kết xuất.
Các giá trị cột âm không bị từ chối; hình chữ nhật cột kéo dài xuống dưới trục X.
Số lượng nhãn và giá trị không được đối chiếu chéo. Bên gọi cung cấp các danh sách có độ dài khớp nhau.
Một ChartBox với kích thước bằng không hoặc âm được chấp nhận và tạo ra đầu ra suy biến; các bên gọi phải định kích thước cho hộp.
Các renderer không clip. Một biểu đồ quá cỡ, các nhãn danh mục dưới vùng vẽ của nó, hoặc một chú giải dài có thể tràn ra ngoài vùng trang dự định.
Một trang thiếu font dưới tên tài nguyên font biểu đồ để lại các toán tử văn bản tham chiếu tới một tài nguyên chưa được định nghĩa; hành vi của trình xem khi đó là không xác định.
ChartColor::hex() không thực hiện xác thực nào; đầu vào ngắn hơn sáu chữ số giải mã các thành phần thiếu thành không. ChartColor::palette() thất bại với TypeError khi chỉ số âm, vì modulo âm của PHP không phân giải khóa palette nào.
Module không thực hiện mật mã nào; chế độ FIPS không có hành vi riêng cho biểu đồ.

Tính phù hợp

Module Chart phát ra các toán tử content-stream PDF. Không có tiêu chuẩn biểu đồ, bộ ký hiệu, hay mật mã bên ngoài nào chi phối đầu ra của nó, nên bề mặt phù hợp duy nhất là luồng toán tử được phát ra.

Tuyên bố	Tiêu chuẩn	Điều khoản
Đồ họa được phát ra theo mô hình toán tử content-stream; đầu ra lồng bên trong một graphics state đã lưu và khôi phục.	ISO 32000-2	§8.1
Cột, đường, sector, và điểm đánh dấu là các đối tượng path: việc dựng bắt đầu với `m` hoặc `re` và kết thúc với một toán tử tô-vẽ-path.	ISO 32000-2	§8.5.2
Nhãn được kết xuất dưới dạng các đối tượng text: vị trí được thiết lập sau `BT`, và các glyph được tô với toán tử hiển-thị-văn-bản `Tj`.	ISO 32000-2	§9.2.2, §9.4.3

Mọi điều khoản đều được diễn giải lại; trang này không sao chép văn bản quy phạm nào. Đây là các tuyên bố năng lực, không phải chứng nhận; NextPDF không giữ chứng nhận nào và không cấp chứng nhận nào. Việc kết xuất luồng đúng cách còn phụ thuộc vào tài liệu bao quanh được định dạng đúng, đó là trách nhiệm của người viết tài liệu.

Ghi chú phát triển

Cả năm lớp đều mang @since 1.9.0 và hiện hành trong nextpdf/pro 3.1.0.
Module khép kín: các renderer chỉ phụ thuộc vào ChartBox và ChartColor, không ghép nối với Core.
Đầu ra tất định giữ cho các tài liệu có biểu đồ tái lập được, ổn định khi diff, và an toàn để ký hoặc lưu trữ.
Đăng ký một font dưới tên tài nguyên font biểu đồ một lần cho mỗi trang chứa biểu đồ.
Tái sử dụng một renderer đã cấu hình trên nhiều hộp thoải mái; render() không thực hiện thay đổi trạng thái nào.
Bằng chứng test nằm dưới pro/tests/Unit/Chart/; ma trận hỗ trợ neo mỗi hàng Verified vào bộ test của nó.

Ranh giới xuất bản

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

Xem thêm

Chart (năng lực) — tổng quan theo hướng tác vụ, cài đặt, và các mẫu mã.
Barcode — Tài liệu tham chiếu chuyên sâu — bề mặt vẽ Pro anh em với ma trận hỗ trợ có bằng chứng riêng của nó.