Flow Layout

Tổng quan nhanh

NextPDF Pro đặt một chuỗi các phần tử luồng — văn bản, hình ảnh, bảng, spacer — lên các trang, gán cho mỗi phần tử một trang và vị trí cụ thể. Hành vi ngắt trang có thể chọn được: greedy, tránh dòng mồ côi, hoặc giữ-cùng-nhau.

Tình trạng cung cấp & cấp phép

Năng lực này đi kèm trong NextPDF Pro (nextpdf/pro) và kích hoạt cùng với một envelope giấy phép 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. Không có cờ giấy phép riêng theo từng tính năng; envelope Pro bật nó lên. So sánh các phiên bản và nhận giấy phép.

Cài đặt

composer require nextpdf/pro:^3

Tổng quan khái niệm

Engine bố cục streaming nhận một danh sách các phần tử luồng và một vùng nội dung, rồi duyệt các phần tử theo thứ tự và gán cho mỗi phần tử một trang và vị trí. Khi một phần tử không vừa với không gian dọc còn lại, engine bắt đầu một trang mới theo chiến lược đã cấu hình:

• StreamingLayoutEngine — engine. Được khởi tạo với một LayoutRegion (vùng nội dung mỗi trang) và một PageBreakStrategy. Nó trả về một LayoutResult gồm các phần tử đã đặt.
• FlowElement / FlowElementType — mô hình phần tử. Văn bản và bảng có thể ngắt qua các trang; engine đặt hình ảnh và spacer một cách nguyên tử.
• PageBreakStrategy — một enum với ba hành vi:
  • Greedy — ngắt ngay khi phần tử kế tiếp không vừa.
  • AvoidOrphans — ngắt sớm khi chỉ còn lại một lượng nhỏ không gian, để tránh để lại một phần tử đơn lẻ ở đầu một trang mới.
  • KeepTogether — tôn trọng cờ giữ-cùng-phần-tử-kế để các phần tử đi cặp ở lại trên cùng một trang khi có thể.

Flow Layout là một engine đặt phần tử. Nó tính toán việc gán trang và vị trí; nó không phải là một engine kết xuất HTML hay CSS. Đối với HTML-sang-PDF, hãy dùng pipeline HTML của Core.

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

Engine gán cho mỗi phần tử một trang và vị trí trong một lượt duyệt xuôi duy nhất. Nó không bao giờ đệm toàn bộ cây tài liệu để reflow về sau. Điều đó giữ bộ nhớ có giới hạn dù tài liệu chạy dài đến đâu, và làm cho chi phí tuyến tính theo số lượng phần tử. Mỗi quyết định ngắt trang là một vị từ cục bộ trên con trỏ hiện tại và chiến lược đã chọn. Nhờ vậy greedy, tránh dòng mồ côi và giữ-cùng-nhau đều được giải quyết trong cùng một lượt duyệt streaming. Đánh đổi là cam kết xuôi: một phần tử quá cao sẽ tràn thay vì được co lại, và giữ-cùng-nhau chỉ đúng khi cả hai phần tử đi cặp cùng chung một trang.

Bối cảnh thiết kế: Sinh tài liệu số lượng lớn.

Bề mặt API

Lớp	Trách nhiệm
StreamingLayoutEngine	Gán trang và vị trí cho các phần tử luồng.
FlowElement, FlowElementType	Mô hình phần tử và enum kiểu.
LayoutRegion	Vùng nội dung mỗi trang.
PageBreakStrategy	Enum hành vi ngắt trang.
LayoutResult, PlacedElement	Đầu ra đặt phần tử.

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

use NextPDF\Pro\FlowLayout\{StreamingLayoutEngine, LayoutRegion, PageBreakStrategy};

$engine = new StreamingLayoutEngine(
    region:   new LayoutRegion(/* x, y, width, height */),
    strategy: PageBreakStrategy::AvoidOrphans,
);
$result = $engine->layout($elements);

Mẫu mã — Production

$result = $engine->layout($elements);
foreach ($result->placements as $placed) {
    $logger->debug('flow.placed', [
        'page' => $placed->pageIndex,
        'type' => $placed->element->type->value,
    ]);
}

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

• Engine vẫn đặt một phần tử cao hơn vùng, nhưng nó có thể tràn; hãy định kích thước các phần tử trong phạm vi chiều cao của vùng.
• KeepTogether chỉ giữ các cặp cùng nhau khi cả hai vừa trên một trang.
• AvoidOrphans dành sẵn ít nhất hai chiều cao phần tử trước khi ngắt.

Hiệu năng

Bố cục là tuyến tính theo số lượng phần tử. Engine là streaming: nó không giữ lại một cây tài liệu đầy đủ.

Ghi chú về bảo mật

Flow Layout hoạt động trên metadata phần tử mà bạn cung cấp. Nó không thực hiện I/O nào.

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

Flow Layout triển khai hành vi đặt phần tử của NextPDF; nó không nhắm tới một tiêu chuẩn bố cục bên ngoài.

Hợp đồng hành vi

• StreamingLayoutEngine được khởi tạo với một LayoutRegion và một PageBreakStrategy và trả về một LayoutResult gồm các phần tử đã đặt với việc gán trang và vị trí cụ thể.
• PageBreakStrategy có ba hành vi: Greedy (ngắt khi phần tử kế tiếp không vừa), AvoidOrphans (ngắt sớm, dành sẵn ít nhất hai chiều cao phần tử) và KeepTogether (tôn trọng giữ-cùng-phần-tử-kế để các phần tử đi cặp ở lại trên một trang khi cả hai vừa).
• Văn bản và bảng có thể ngắt qua các trang; hình ảnh và spacer được đặt một cách nguyên tử. Một phần tử cao hơn vùng vẫn được đặt nhưng có thể tràn.
• Engine là streaming: nó không giữ lại một cây tài liệu đầy đủ và không thực hiện I/O nào.
• Đây là một engine đặt phần tử. Nó tính toán việc gán trang và vị trí; nó không phải là một engine kết xuất HTML hay CSS.

Ghi chú ranh giới Enterprise

Enterprise không thay đổi hành vi của Flow Layout. Enterprise bổ sung các tính năng bậc cao hơn được ghi tài liệu riêng; chúng không bắt buộc để sử dụng engine đặt phần tử.

Phương án dự phòng / thay thế trong Core

Không có engine đặt phần tử của Core với các chiến lược ngắt trang. Đối với kết xuất HTML-sang-PDF, hãy dùng pipeline HTML của Core mã nguồn mở. Xem /modules/html/.

Ranh giới công bố

Trang này chỉ ghi tài liệu về hành vi có thể quan sát từ bên ngoài và bề mặt API công khai được hỗ trợ. Đườ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 đều nằm ngoài phạm vi.

Xem thêm

• Flow Layout — Tham chiếu sâu — tham chiếu đầy đủ về lớp và phương thức.
• Document — lắp ráp tài liệu.
• Module HTML của Core — kết xuất HTML-sang-PDF.