Bố cục: đầu trang, chân trang, cột, sách gấp và trình quản lý trang

Tổng quan nhanh

Module Layout chứa các engine bố trí trang đứng sau facade Document: đầu trang, chân trang, bố cục nhiều cột, áp trang sách gấp khâu giữa và các thao tác trang mang tính cấu trúc. Module này nhỏ gọn và ổn định: sáu lớp, tất cả đều @since 1.0.0.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Layout (src/Layout/, sáu lớp, @since 1.0.0) là lớp engine bên dưới concern HasLayout. Ứng dụng của bạn gọi các phương thức facade trên Document; trait sẽ định tuyến từng lệnh gọi đến một trong các engine này. Manifest đánh dấu module này có mức rủi ro standard và độ ổn định internal, với Core là phần phụ thuộc duy nhất. Hãy sử dụng module này thông qua facade, đừng khởi tạo trực tiếp các lớp.

HeaderFooter kết xuất phần đầu trang và chân trang lặp lại. Nó lưu trạng thái tiêu đề, mô tả, logo, phông chữ, lề và màu sắc cho từng dải. Nó phát ra các toán tử luồng nội dung Portable Document Format (PDF) theo yêu cầu thông qua renderHeader() và renderFooter(). Theo mặc định, chân trang in chuỗi "page / total" căn phải. setHeaderCallback() và setFooterCallback() thay bố cục mặc định bằng một closure do bên gọi cung cấp. getHeaderContentHeight() cho biết khoảng không gian dọc mà đầu trang chiếm, để phần thân trang có thể bắt đầu bên dưới nó. Khi tài liệu ở chế độ PDF có thẻ, HasPages chặn đầu trang tự động ở phía trên vì nội dung đầu trang nằm ngoài cây cấu trúc.

ColumnLayout quản lý luồng nội dung nhiều cột. setEqualColumns(int $count, float $totalWidth, float $gap = 5) chia chiều rộng khả dụng thành các cột bằng nhau. setColumnsArray() nhận vị trí và chiều rộng ColumnDefinition được chỉ định rõ ràng. Dùng selectColumn() để chọn một cột, hoặc nextColumn() để chuyển sang cột kế tiếp. getCurrentColumnX() / getCurrentColumnWidth() trả về thông tin hình học của cột đang hoạt động. Số cột không hợp lệ, khoảng cách âm, hoặc chiều rộng cột tính ra không dương sẽ làm phát sinh PageLayoutException.

BookletLayout sắp xếp lại các trang cho kiểu đóng khâu giữa (gấp giữa). reorderPages() đệm danh sách trang lên thành bội số của bốn vì một tờ sách gấp chứa bốn ô trang, rồi áp trang từ ngoài vào trong để các tờ sau khi gấp và bấm ghim đọc đúng thứ tự. getMarginAdjustments() trả về lề trong (gáy) và lề ngoài (mép) cho mỗi mặt tại một vị trí cho trước. getSheetCount() cho biết số tờ hai mặt cần cho một số lượng trang. Việc sắp xếp lại chỉ thay đổi vị trí đặt nội dung. Trình tự trang PDF bên dưới vẫn tuyến tính, nhất quán với cây trang, vốn xác định thứ tự các trang trong tài liệu (ISO 32000-2 §7.7).

PageManager cung cấp các thao tác trang mang tính cấu trúc, tách biệt với việc kết xuất nội dung. movePage(), copyPage() và deletePage() thao tác trên mảng PageData theo tham chiếu. Vùng trang (addPageRegion(), isInRegion(), getRegionOffset()) xác định các vùng không được ghi. Nhóm trang (startPageGroup(), getGroupPageNo()) hỗ trợ đánh số trang theo từng phần. PageRegion và ColumnDefinition là hai đối tượng giá trị mà các engine này sử dụng. Module Writer tuần tự hóa các trang thu được thành một cây trang, trong đó mục Kids là một mảng các tham chiếu gián tiếp đến các con trực tiếp của một nút cây trang (ISO 32000-2 §7.7.3.2).

Bề mặt API

Ký hiệu	Loại	Độ ổn định	Từ phiên bản
HeaderFooter::setHeaderData(string, string, string, float): self	phương thức	ổn định	1.0.0
HeaderFooter::setHeaderFont(string, float): self / setHeaderMargin(float): self	phương thức	ổn định	1.0.0
HeaderFooter::setFooterFont(string, float): self / setFooterMargin(float): self	phương thức	ổn định	1.0.0
HeaderFooter::setHeaderCallback(Closure): self / setFooterCallback(Closure): self	phương thức	ổn định	1.0.0
HeaderFooter::getHeaderContentHeight(): float	phương thức	ổn định	1.0.0
HeaderFooter::renderHeader(float, float, float, float, int, int): string	phương thức	ổn định	1.0.0
HeaderFooter::renderFooter(float, float, float, float, int, int, string): string	phương thức	ổn định	1.0.0
ColumnLayout::setEqualColumns(int, float, float): self	phương thức	ổn định	1.0.0
ColumnLayout::setColumnsArray(array): self / resetColumns(): self	phương thức	ổn định	1.0.0
ColumnLayout::selectColumn(int): self / nextColumn(): bool	phương thức	ổn định	1.0.0
ColumnLayout::getCurrentColumnX(float): float / getCurrentColumnWidth(float): float	phương thức	ổn định	1.0.0
BookletLayout::setBooklet(bool, float, float): void	phương thức	ổn định	1.0.0
BookletLayout::reorderPages(array): array	phương thức	ổn định	1.0.0
BookletLayout::getMarginAdjustments(int): array{left: float, right: float}	phương thức	ổn định	1.0.0
BookletLayout::getSheetCount(int): int	phương thức	ổn định	1.0.0
PageManager::movePage(int, int, array): void / copyPage(int, array): void / deletePage(int, array): void	phương thức	ổn định	1.0.0
PageManager::addPageRegion(float, float, float, float): void / isInRegion(float, float): bool	phương thức	ổn định	1.0.0
PageManager::getRegionOffset(float, float, float, float): float	phương thức	ổn định	1.0.0
PageManager::startPageGroup(): void / getGroupPageNo(int): int	phương thức	ổn định	1.0.0
PageRegion / ColumnDefinition	đối tượng mang giá trị	ổn định	1.0.0

Mẫu mã — bắt đầu nhanh

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Header and Footer');

$doc->setHeaderData(
    title: 'NextPDF Example',
    description: 'Header and Footer Demonstration',
);
$doc->setHeaderFont('helvetica', 10);
$doc->setHeaderMargin(5);
$doc->setFooterFont('helvetica', 8);
$doc->setFooterMargin(10);

$doc->addPage();
$doc->setFont('helvetica', 'B', 16);
$doc->cell(0, 12, 'Document with Header and Footer', newLine: true);

$doc->save(__DIR__ . '/output/13-header-footer.pdf');

Nguồn: examples/13-header-footer.php. Đầu trang được kết xuất ở mỗi lệnh gọi addPage(); chân trang được kết xuất khi trang được flush.

Mẫu mã — môi trường thật

Một callback chân trang điều khiển văn bản số trang, còn engine cột dẫn dắt phần thân hai cột. Bạn truy cập cả hai engine thông qua facade.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Two-Column Report');

$doc->setFooterCallback(static function (Document $d): void {
    $d->setFont('helvetica', '', 8);
    $d->text(180.0, 285.0, 'Page ' . ($d->getPage() + 1));
});

$doc->addPage();
$doc->setEqualColumns(2, gap: 8);
$doc->selectColumn(0);
$doc->setFont('helvetica', '', 10);
$doc->multiCell(0, 6, 'Left column flows here.');
$doc->selectColumn(1);
$doc->multiCell(0, 6, 'Right column flows here.');

$doc->save(__DIR__ . '/output/two-column-report.pdf');

Nguồn: mẫu được lấy từ examples/13-header-footer.php.

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

• setEqualColumns() từ chối số cột nhỏ hơn 1, khoảng cách âm, hoặc bất kỳ bố cục nào có chiều rộng cột tính ra không dương. Nó làm phát sinh PageLayoutException thay vì trả về một bố cục suy giảm.
• selectColumn() bỏ qua chỉ mục ngoài phạm vi và giữ nguyên cột hiện tại; nó không bao giờ ném ngoại lệ với chỉ mục không hợp lệ. nextColumn() trả về false khi đã ở cột cuối cùng.
• BookletLayout::reorderPages() đệm lên thành bội số của bốn bằng các trang trắng, sao chép kích thước từ trang cuối cùng. Một danh sách trang rỗng trả về một mảng rỗng. Việc sắp xếp lại chỉ ảnh hưởng đến vị trí; các chỉ mục của movePage() vẫn tham chiếu theo thứ tự logic.
• PageManager::movePage(), copyPage() và deletePage() âm thầm không làm gì với chỉ mục ngoài phạm vi; chúng kiểm tra bằng isset() và trả về mà không sửa đổi mảng. Hãy tự kiểm tra chỉ mục khi thiếu trang là lỗi của bên gọi.
• getHeaderContentHeight() trả về 0.0 khi đầu trang bị tắt hoặc không có cả tiêu đề lẫn mô tả. Khi đó, phần thân trang bắt đầu tại lề trên.
• Ở chế độ PDF có thẻ, đầu trang tự động bị chặn ở phía trên. Hãy xây dựng một bố cục nhận biết cấu trúc cho các tài liệu dễ tiếp cận.

Hiệu năng

Việc kết xuất đầu trang và chân trang nối thêm các toán tử vào bộ đệm trang đang hoạt động theo O(nội dung bố trí); chi phí tỷ lệ với tiêu đề, mô tả và đường phân cách được ghi, chứ không theo kích thước tài liệu. Phép tính cột là O(1) cho mỗi lệnh gọi. BookletLayout::reorderPages() là O(n) theo số trang, với một lượt đệm chỉ thực hiện một lần; vòng lặp áp trang chạm vào mỗi ô đã đệm đúng một lần. Các phép kiểm vùng của PageManager là O(số vùng) cho mỗi điểm, còn các thao tác trang là các phép cắt ghép mảng O(n). Các engine này không giữ trạng thái theo từng trang trên toàn bộ tài liệu, nên chúng không làm tăng mức dùng bộ nhớ trên các tài liệu dài. Chi phí bộ nhớ chủ đạo là luồng nội dung được tích lũy, như trình bày trong khái niệm luồng và bộ nhớ. Cổng kiểm soát độ trễ và ngân sách bộ nhớ của pipeline HyperText Markup Language (HTML) được ghi trong PERFORMANCE-BUDGETS; nó chỉ giới hạn đường kết xuất HTML và không kiểm soát trực tiếp các engine bố cục này. performance_budget 1500 ms / 64 MB là phạm vi canvas cho phần bắt đầu nhanh, không phải hợp đồng cho mỗi lệnh gọi.

Lưu ý bảo mật

Các engine này tiêu thụ các chuỗi và một đường dẫn logo do bên gọi cung cấp. Đường dẫn logo đi qua engine ảnh, vốn xác thực tệp trước khi nhúng. renderHeader() và renderFooter() escape chuỗi cho tiêu đề, mô tả và văn bản số trang qua bộ escape chuỗi PDF tập trung trước khi chúng đi vào luồng nội dung, nên văn bản của bên gọi không thể thoát khỏi ngữ pháp chuỗi nguyên văn. Một callback đầu trang hoặc chân trang chạy mã của bên gọi với cùng mức tin cậy như phần còn lại của tài liệu; hãy xử lý tương xứng mọi dữ liệu bên ngoài mà nó đọc. Các thao tác trang của PageManager di chuyển tham chiếu đến PageData hiện có; chúng không phân tích các byte không tin cậy.

Tuân thủ

Tuyên bố	Tiêu chuẩn	Điều khoản	Bằng chứng
Việc sắp xếp lại trang cho đầu ra sách gấp chỉ thay đổi vị trí; cây trang vẫn xác định thứ tự tuyến tính của các trang trong tài liệu.	ISO 32000-2	§7.7
Mục Kids của nút cây trang đã tuần tự hóa là một mảng các tham chiếu gián tiếp đến các con trực tiếp của nút đó.	ISO 32000-2	§7.7.3.2

Bảng diễn giải từng điều khoản và giữ cố định các thuật ngữ trong bảng chú giải; bảng không tái hiện văn bản quy phạm.

Xem thêm

• Trait Core/HasLayout — concern facade kết hợp các engine bố cục.
• Trait Core/HasPages — kích thước trang và lề được phép tính cột sử dụng.
• Writer — bộ phát đối tượng PDF và cây trang, tuần tự hóa các trang đã được bố trí.
• Luồng và bộ nhớ — vì sao các engine bố trí không giữ trạng thái theo từng trang, và đường kết xuất bị giới hạn bởi bộ nhớ hoạt động ra sao.
• Ràng buộc HTML / Streaming (ADR-001) — lý do của phạm vi streaming một lượt.