Pro phiên bản

Flow Layout — 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 chuyên sâu cho module Pro Flow Layout. Nó bao quát engine đặt phần tử, mô hình phần tử, các chiến lược ngắt trang, hợp đồng hành vi của chúng, và các chế độ lỗi. StreamingLayoutEngine duyệt một danh sách các giá trị FlowElement theo thứ tự. Nó gán cho mỗi phần tử một chỉ số trang bắt đầu từ 0 và một vị trí bên trong một LayoutRegion. Kết quả là một LayoutResult gồm các bản ghi PlacedElement bất biến. Module chỉ tính toán việc đặt phần tử; nó không kết xuất gì và không thực hiện I/O.

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

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

Không tồn tại cờ giấy phép theo từng tính năng. Đây là một năng lực của phiên bản Pro.

Bề mặt API công khai

Tất cả các symbol nằm trong namespace NextPDF\Pro\FlowLayout. Tất cả các value object đều là final và bất biến.

Symbol	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`StreamingLayoutEngine::__construct`	`LayoutRegion $region`, `PageBreakStrategy $strategy = PageBreakStrategy::Greedy`	Gắn một vùng nội dung theo từng trang với một chiến lược ngắt	`StreamingLayoutEngine`	—	Chiến lược mặc định là `Greedy`.
`StreamingLayoutEngine::layout`	`list<FlowElement> $elements`	Một lượt duyệt xuôi; đặt tuần tự với các ngắt trang do chiến lược dẫn dắt	`LayoutResult`	Không bao giờ ném	Danh sách rỗng cho ra một trang rỗng.
`StreamingLayoutEngine::withStrategy`	`PageBreakStrategy $strategy`	Suy ra một engine mới với cùng vùng	`self`	—	Đối tượng nhận không thay đổi.
`StreamingLayoutEngine::withRegion`	`LayoutRegion $region`	Suy ra một engine mới với cùng chiến lược	`self`	—	Đối tượng nhận không thay đổi.
`FlowElement::__construct`	`FlowElementType $type`, `string $content`, `float $widthPt = 0`, `float $heightPt = 0`, `float $marginTopPt = 0`, `float $marginBottomPt = 0`, `bool $keepWithNext = false`	Value object phần tử bất biến	`FlowElement`	—	Đường khởi tạo duy nhất cho phần tử `Table`.
`FlowElement::text`	`string $content`, `float $height`	Phần tử text với chiều cao do bên gọi đo	`self` (static)	—	Chiều rộng 0 sẽ phân giải thành chiều rộng vùng lúc đặt.
`FlowElement::image`	`string $path`, `float $width`, `float $height`	Phần tử image; `content` mang đường dẫn	`self` (static)	—	Engine không bao giờ mở tệp.
`FlowElement::spacer`	`float $height`	Khoảng trắng dọc với nội dung rỗng	`self` (static)	—	—
`FlowElement::pageBreak`	—	Dấu ngắt tường minh	`self` (static)	—	Không phát ra `PlacedElement` nào.
`FlowElement::totalHeight`	—	Chiều cao cộng với lề trên và lề dưới	`float`	—	Mọi kiểm tra vừa vặn đều dùng giá trị này.
`FlowElementType`	các case enum `Text`, `Image`, `Table`, `Spacer`, `PageBreak`	Nền là chuỗi: `text`, `image`, `table`, `spacer`, `page_break`	—	—	—
`FlowElementType::isBreakable`	—	`Text` và `Table` trả về true; các loại khác trả về false	`bool`	—	Chỉ phân loại; xem hợp đồng đặt nguyên tử bên dưới.
`LayoutRegion::__construct`	`float $x`, `float $y`, `float $width`, `float $height`	Hộp nội dung gốc góc trên-trái, đo bằng point	`LayoutRegion`	—	Không xác thực; các giá trị được nhận nguyên trạng.
`LayoutRegion::contains`	`float $px`, `float $py`	Kiểm tra điểm-trong-vùng bao gồm biên	`bool`	—	—
`LayoutRegion::remainingHeight`	`float $currentY`	Chiều cao vùng trừ đi độ lệch dọc đã tiêu thụ	`float`	—	Bằng 0 hoặc âm khi con trỏ đã tràn.
`LayoutResult::__construct`	`list<PlacedElement> $placements`, `int $pageCount`, `float $totalHeightPt`	Kết quả bố cục bất biến	`LayoutResult`	—	—
`LayoutResult::placementsOnPage`	`int $pageIndex`	Lọc các placement theo chỉ số trang bắt đầu từ 0	`list<PlacedElement>`	—	Danh sách trả về được đánh chỉ số lại.
`LayoutResult::isEmpty`	—	True khi không có phần tử nào được đặt	`bool`	—	True cho đầu vào rỗng và chỉ-có-ngắt.
`PageBreakStrategy`	các case enum `Greedy`, `AvoidOrphans`, `KeepTogether`	Nền là chuỗi: `greedy`, `avoid_orphans`, `keep_together`	—	—	—
`PageBreakStrategy::label`	—	Nhãn chiến lược dễ đọc cho người	`string`	—	—
`PlacedElement::__construct`	`FlowElement $element`, `int $pageIndex`, `float $x`, `float $y`, `float $width`, `float $height`	Bản ghi đặt phần tử bất biến	`PlacedElement`	—	Tọa độ tính bằng point, gốc góc trên-trái.

public function layout(array $elements): LayoutResult
public function withStrategy(PageBreakStrategy $strategy): self
public function withRegion(LayoutRegion $region): self

public static function text(string $content, float $height): self
public static function image(string $path, float $width, float $height): self
public static function spacer(float $height): self
public static function pageBreak(): self

Hợp đồng hành vi

StreamingLayoutEngine::layout() thực hiện một lượt duyệt xuôi trên danh sách đầu vào. Với mỗi phần tử, nó kiểm tra sự vừa vặn, ngắt trang khi cần, rồi ghi lại một PlacedElement. Một danh sách đầu vào rỗng trả về một LayoutResult không có placement nào, số trang là 1, và tổng chiều cao là 0.

Hình học đặt phần tử mang tính tất định:

x là mép trái của vùng.
y là vị trí con trỏ hiện tại cộng với lề trên của phần tử.
width là widthPt của phần tử khi dương, ngược lại là chiều rộng vùng.
height là heightPt của phần tử, đúng như được cung cấp.

Sau mỗi lần đặt, con trỏ tiến lên theo totalHeight(), gồm cả lề. Cùng một lượng đó được cộng dồn vào LayoutResult::totalHeightPt.

Các quy tắc ngắt trang, theo thứ tự đánh giá:

Một phần tử PageBreak tường minh tăng chỉ số trang và đặt lại con trỏ về đỉnh vùng. Nó không phát ra placement và không cộng gì vào tổng chiều cao.
Khi totalHeight() của một phần tử vượt quá chiều cao còn lại, engine ngắt — trừ khi con trỏ đã ở đỉnh trang.
Greedy không thêm điều kiện nào khác: các phần tử vừa vặn luôn được đặt.
AvoidOrphans ngắt trước một phần tử vừa vặn khi khoảng trống còn lại sau khi đặt sẽ dương nhưng dưới một nửa chiều cao yêu cầu của chính phần tử đó. Chiều cao của chính phần tử là đơn vị tham chiếu, với số chia cố định là hai; không có số đo font nào tham gia. Nó không bao giờ ngắt ở đỉnh một trang.
KeepTogether ngắt trước một phần tử vừa vặn khi cờ keepWithNext của nó được đặt, tồn tại một phần tử kế tiếp, con trỏ không ở đỉnh trang, và tổng totalHeight() gộp của cả hai phần tử vượt quá khoảng trống còn lại. Cờ trên phần tử cuối cùng không có tác dụng.

Đặt nguyên tử: engine đặt mỗi phần tử như một khối. Nó không bao giờ tách nội dung phần tử qua nhiều trang. FlowElementType::isBreakable() phân loại loại nào mà bên gọi có thể chia trước thành các phần tử nhỏ hơn; bản thân engine không tham chiếu nó.

Tính không trạng thái và tính tất định: engine chỉ giữ vùng và chiến lược của nó. layout() không chia sẻ trạng thái giữa các lần gọi, và đầu vào giống nhau tạo ra kết quả giống nhau. withStrategy() và withRegion() trả về các engine mới và không bao giờ biến đổi đối tượng nhận.

Trường hợp biên & chế độ lỗi

Không phương thức nào trong module này ném. Không có phân cấp ngoại lệ nào để bắt.
Các constructor không xác thực gì. Kích thước vùng âm hoặc bằng 0, chiều cao phần tử âm, và lề âm đều được chấp nhận và đi qua phép tính không đổi.
Một phần tử cao hơn vùng vẫn được đặt. Ở đỉnh một trang nó được đặt tại đó và tràn ra; ở nơi khác engine ngắt trước và nó tràn ra một trang mới. Phần tử kế tiếp khi đó luôn kích hoạt một lần ngắt, nên sự tràn bị giới hạn trong một trang.
Một PageBreak dẫn đầu đặt phần tử nội dung đầu tiên vào chỉ số trang 1, cho ra số trang ít nhất là 2.
Các phần tử PageBreak liên tiếp mỗi cái đều đẩy bộ đếm trang, tạo ra các trang trống. Một cái ở cuối để lại một trang rỗng cuối cùng trong pageCount.
Keep-together chỉ giữ được khi cả hai phần tử ghép đôi cùng vừa trên một trang. Một cặp có chiều cao gộp vượt quá một trang đầy vẫn bị tách.
Một widthPt không dương sẽ phân giải thành chiều rộng vùng; kiểm tra thay thế là lớn hơn hẳn 0.
remainingHeight() có thể trả về 0 hoặc một giá trị âm khi con trỏ đã tràn. contains() coi biên vùng là nằm trong.
placementsOnPage() với một chỉ số ngoài phạm vi trả về một danh sách rỗng.
Module này không thực hiện thao tác mã hóa nào và không định nghĩa hành vi đặc thù cho FIPS.

Tính phù hợp

Flow Layout hiện thực hành vi đặt phần tử do NextPDF định nghĩa. Nó không nhắm tới một tiêu chuẩn bố cục hay đánh máy bên ngoài, nên trang này không mang bảng trích dẫn quy phạm. Các chiến lược ngắt trang là ngữ nghĩa của NextPDF; chúng không phải là hiện thực của các thuộc tính phân mảnh CSS hay của bất kỳ mô hình keep XSL-FO nào. Mọi kích thước đều được biểu diễn bằng point, khớp với đơn vị mà Core writer tiêu thụ.

Những phát biểu này chỉ mô tả năng lực. NextPDF không nắm giữ chứng nhận phù hợp nào, và không có tuyên bố chứng nhận nào được đưa ra hay ngụ ý.

Ghi chú phát triển

Đo nội dung ở phía trên. Engine tiêu thụ các chiều cao do bên gọi cung cấp; nó không có số đo font và không thực hiện đo đạc văn bản.
Chia trước nội dung text hoặc table dài thành nhiều phần tử trước khi bố cục. Dùng isBreakable() để quyết định loại nào mà một bộ chia có thể tách.
Tái sử dụng một engine cho mỗi hình học trang. Suy ra các biến thể với chi phí thấp bằng withStrategy() và withRegion().
Gom đầu ra theo từng trang bằng placementsOnPage() khi kết xuất trang từng trang một.
Bố cục là một lượt duyệt duy nhất, tuyến tính theo số lượng phần tử, và không giữ lại cây tài liệu. Kết quả mang tính tất định, phù hợp cho các bài kiểm thử golden-file.
Để kết xuất HTML-sang-PDF, dùng pipeline Core HTML thay thế; module này không phải là một engine HTML hay CSS.

Ranh giới công bố

Trang này chỉ ghi lại hành vi có thể quan sát 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ộ, các class hỗ trợ, các bảng cơ chế, các tên tệp runbook, và các tiền tố ticket đều nằm ngoài phạm vi.