跳到內容
NextPDF

加入會重複出現的頁首與頁尾

重點速覽

標題為「重點速覽」的區段

設定一次頁首（一個標題加一段說明）與頁尾後，layout 引擎就會在每一頁繪製它們，包括自動分頁產生的頁面。請在第一次 addPage() 之前完成資料設定。你不需要逐頁繪製頁首或頁尾。這則範例依循 examples/13-header-footer.php。

安裝

標題為「安裝」的區段
Terminal window
composer require nextpdf/core:^3

不需要任何選用擴充套件。Layout concern 上的頁首與頁尾 API 自 1.0.0 起即維持穩定，並可在 8.1–8.4 backport 矩陣上執行。

概念總覽

標題為「概念總覽」的區段

頁首與頁尾是頁面裝飾元素。layout 引擎會在每一頁清出（flush）時，於頁面預留的上、下兩個區帶繪製它們。setHeaderData() 用來記錄內容。setHeaderFont()、setHeaderMargin()、setFooterFont() 與 setFooterMargin() 用來設定排版字體與距頁面邊緣的距離。若文件不需要這些裝飾元素，可使用 setPrintHeader(false) 與 setPrintFooter(false) 關閉。

頁首與頁尾的幾何位置是以頁面邊界為基準量測。頁面物件字典（ISO 32000-2 §7.7.3.3）將 MediaBox 項目定義為媒材邊界，並將 CropBox 項目定義為頁面裁切後的可見區域。14.11.2 節詳述了這些頁面邊界的語意。你設定的頁首邊距，就是相對於該邊界的偏移量。頁首與頁尾的標記並非獨立物件；它們是每一頁 Contents stream 的一部分，會逐頁輸出（§7.7.3.3）。

API 介面

標題為「API 介面」的區段

API 介面由 PHPDoc 自動產生。這則範例會用到以下方法：

  • setHeaderData(string $title = '', string $description = '', string $logo = '', float $logoWidth = 0): static — 設定頁首內容。
  • setHeaderFont(string $family, float $size = 10): static / setFooterFont(string $family, float $size = 8): static — 設定頁首與頁尾的排版字體。
  • setHeaderMargin(float $margin): static / setFooterMargin(float $margin): static — 設定距頁面邊緣的距離，以毫米為單位。
  • setPrintHeader(bool $enabled): static / setPrintFooter(bool $enabled): static — 切換這些裝飾元素是否輸出。

程式碼範例 — 快速上手

標題為「程式碼範例 — 快速上手」的區段
<?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');

程式碼範例 — 正式環境

標題為「程式碼範例 — 正式環境」的區段

這是可直接在測試載具（harness）中執行的完整範例。它會尊重 NEXTPDF_COOKBOOK_OUTPUT，且不會自行固定任何亂數種子。

<?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";

邊界情況與陷阱

標題為「邊界情況與陷阱」的區段
  • 請在第一頁之前設定好這些裝飾元素。 若在 addPage() 之後才呼叫 setHeaderData()，先前的頁面不會被重繪，因此請在第一次 addPage() 之前完成設定。
  • 頁首邊距與內文上邊距的差異。 頁首邊距是頁首相對於頁面邊緣的距離，與內文上邊距彼此獨立。若內文上邊距小於頁首區帶，兩者就可能重疊；請預留足夠空間。
  • 關閉裝飾元素是針對整份文件，而非單頁。 setPrintHeader(false) 會套用到整份文件。不提供內建的逐頁開關。若需要不含裝飾元素的封面頁，應將它做成另一份獨立文件，或視為刻意的版面設計選擇。
  • Logo 路徑。 傳給 setHeaderData() 的 $logo 引數值是一個本機檔案路徑。影像載入器會拒絕 URL scheme（請參閱影像範例），因此請傳入本機檔案。

效能

標題為「效能」的區段

頁首與頁尾會逐頁繪製。其成本取決於裝飾元素的內容量（少量幾段文字），而非內文大小，因此每次頁面清出（flush）只會增加可忽略的額外負擔。2000 ms / 64 MB 的預算足以涵蓋一份每頁都帶裝飾元素、長達數百頁的文件。

安全性注意事項

標題為「安全性注意事項」的區段

頁首的標題與說明會被當作文件文字繪製。若其中包含使用者可控資料（例如租戶名稱），就必須比照內文限制長度並進行清理。這則範例不執行任何剖析，也不存取網路。

符合性

標題為「符合性」的區段
陳述規範條款參考 ID（reference_id）
MediaBox 這個頁面物件字典項目定義了頁面的媒材邊界，header/footer 的幾何位置即以此為基準量測。ISO 32000-2§7.7.3.3
CropBox 這個頁面物件字典項目是頁面裁切後的可見區域。ISO 32000-2§7.7.3.3
頁首與頁尾的標記是每一頁 Contents stream 的一部分。ISO 32000-2§7.7.3.3

可重現性側寫 — 結構層級。 trailer 中的 /ID 以及 /CreationDate / /ModDate 原子，會在每次儲存時變動。測試載具會剝除這些原子，再比對經 qpdf 正規化後的結構。這則範例描述 NextPDF 如何產生這套結構；它並不主張全面符合 ISO 32000-2。

商業情境

標題為「商業情境」的區段

不適用。會重複出現的頁首與頁尾是 Core 的能力，沒有 Premium gate。

另請參閱

標題為「另請參閱」的區段