Thêm đầu trang và chân trang lặp lại trên từng trang

Tổng quan nhanh

Cấu hình đầu trang (gồm tiêu đề và mô tả) cùng chân trang một lần. Layout engine kết xuất chúng trên từng trang, kể cả các trang được tạo do ngắt trang tự động. Đặt dữ liệu trước lần addPage() đầu tiên. Bạn không cần vẽ riêng đầu trang hay chân trang cho từng trang. Công thức này dựa trên examples/13-header-footer.php.

Cài đặt

composer require nextpdf/core:^3

Không cần phần mở rộng tùy chọn nào. API đầu trang và chân trang trong concern Layout đã ổn định kể từ 1.0.0. API này chạy trên ma trận backport 8.1–8.4.

Tổng quan khái niệm

Đầu trang và chân trang là các thành phần cố định của trang. Layout engine vẽ chúng trong các dải trên và dưới đã dành sẵn cho mỗi trang khi xuất trang. setHeaderData() ghi lại nội dung. setHeaderFont(), setHeaderMargin(), setFooterFont() và setFooterMargin() thiết lập kiểu chữ và khoảng cách đến mép trang. setPrintHeader(false) và setPrintFooter(false) tắt các thành phần này cho những tài liệu không cần chúng.

Hình học của đầu trang và chân trang được đo tương đối với ranh giới trang. Từ điển đối tượng trang (ISO 32000-2 §7.7.3.3) định nghĩa mục MediaBox là ranh giới của vật liệu và mục CropBox là vùng hiển thị mà trang được cắt theo. Phần 14.11.2 định nghĩa ngữ nghĩa của các ranh giới trang đó. Lề đầu trang mà bạn đặt là độ lệch tính từ ranh giới này. Các dấu của đầu trang và chân trang không phải là đối tượng riêng biệt; chúng là một phần của luồng Contents của mỗi trang và được phát ra theo từng trang (§7.7.3.3).

Bề mặt API

Bề mặt API được sinh từ PHPDoc. Công thức này dùng các phương thức sau:

setHeaderData(string $title = '', string $description = '', string $logo = '', float $logoWidth = 0): static — đặt nội dung đầu trang.
setHeaderFont(string $family, float $size = 10): static / setFooterFont(string $family, float $size = 8): static — đặt kiểu chữ cho đầu trang và chân trang.
setHeaderMargin(float $margin): static / setFooterMargin(float $margin): static — đặt khoảng cách đến mép trang, tính bằng milimét.
setPrintHeader(bool $enabled): static / setPrintFooter(bool $enabled): static — bật hoặc tắt các thành phần cố định.

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->setHeaderData(title: 'Quarterly Report', description: 'Confidential');
$doc->setHeaderFont('helvetica', 10);
$doc->setFooterFont('helvetica', 8);

$doc->addPage();
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Body text. The header and footer appear on this page '
    . 'and on every page added afterwards, with no per-page code.');
$doc->addPage();
$doc->multiCell(0, 7, 'Page 2 — the furniture repeats automatically.');

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/header-footer.pdf');

Mẫu mã — Production

Ví dụ hoàn chỉnh sẵn sàng chạy trong harness này, tôn trọng NEXTPDF_COOKBOOK_OUTPUT và không tự cố định entropy.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

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

// Configure the header once, before the first page. The layout engine
// draws it on every page, including auto-break pages.
$doc->setHeaderData(
    title: 'NextPDF Example',
    description: 'Header and Footer Demonstration',
);
$doc->setHeaderFont('helvetica', 10);
$doc->setHeaderMargin(5);

// Configure the footer. The footer band carries the page number.
$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->ln(5);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'This document has a header with a title and description '
    . 'that repeats on every page. The footer shows the page number.');

$doc->addPage();
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'This is page 2. The header and footer appear without '
    . 'any additional code on each new page.');

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/header-footer.pdf';
$doc->save($out);

echo "Created header-footer.pdf\n";

Trường hợp đặc biệt và lưu ý

Thiết lập các thành phần cố định trước trang đầu tiên. Việc gọi setHeaderData() sau addPage() không vẽ lại những trang trước đó, vì vậy hãy cấu hình dữ liệu này trước lần addPage() đầu tiên.
Lề đầu trang so với lề trên của nội dung. Lề đầu trang là khoảng cách từ đầu trang đến mép trang. Nó độc lập với lề trên của phần thân. Hai vùng này có thể chồng lên nhau nếu lề trên của phần thân nhỏ hơn dải đầu trang, vì vậy hãy chừa khoảng trống phía trên.
Tắt các thành phần cố định theo tài liệu, không phải theo trang. setPrintHeader(false) áp dụng cho toàn bộ tài liệu. Không có công tắc tích hợp sẵn để bật tắt theo từng trang. Đối với trang bìa không có các thành phần cố định, hãy dùng một tài liệu riêng hoặc chọn một bố cục có chủ đích.
Đường dẫn logo. Tham số $logo của setHeaderData() là một đường dẫn tệp cục bộ. Trình tải ảnh từ chối lược đồ URL (xem công thức về hình ảnh), vì vậy hãy dùng tệp cục bộ.

Hiệu năng

Việc kết xuất đầu trang và chân trang chạy theo từng trang. Chi phí tỷ lệ theo nội dung của các thành phần cố định (một vài đoạn văn bản), không theo kích thước phần thân. Phần chi phí phụ cho mỗi lần xuất trang là không đáng kể. Ngân sách 2000 ms / 64 MB đủ cho một tài liệu nhiều trăm trang có các thành phần cố định trên từng trang.

Lưu ý về bảo mật

Tiêu đề và mô tả của đầu trang được kết xuất dưới dạng văn bản tài liệu. Nếu chúng chứa dữ liệu do người dùng kiểm soát, chẳng hạn như tên một tenant, hãy giới hạn độ dài và làm sạch dữ liệu đó theo cùng cách bạn xử lý văn bản phần thân. Công thức này không phân tích cú pháp và không truy cập mạng.

Mức độ tuân thủ

Phát biểu	Đặc tả	Điều khoản
`MediaBox` là mục từ điển đối tượng trang định nghĩa ranh giới vật liệu của trang mà hình học header/footer được đo theo.	ISO 32000-2	§7.7.3.3
`CropBox` là mục từ điển đối tượng trang, là vùng hiển thị mà trang được cắt theo.	ISO 32000-2	§7.7.3.3
Các dấu header/footer là một phần của luồng `Contents` của mỗi trang.	ISO 32000-2	§7.7.3.3

Hồ sơ khả năng tái tạo — cấu trúc. Các atom /ID trong trailer và /CreationDate / /ModDate thay đổi ở mỗi lần lưu. Harness loại bỏ các atom đó, sau đó so sánh cấu trúc đã chuẩn hóa bằng qpdf. Công thức này mô tả cách NextPDF tạo ra cấu trúc. Nó không khẳng định mức độ tuân thủ ISO 32000-2 như một tuyên bố bao quát.

Bối cảnh thương mại

Không áp dụng. Đầu trang và chân trang lặp lại là một tính năng của Core, không bị giới hạn bởi Premium.