เพิ่มส่วนหัวและส่วนท้ายที่ทำซ้ำในทุกหน้า

ภาพรวมโดยสังเขป

กำหนดค่าส่วนหัว (ชื่อเรื่องและคำอธิบาย) และส่วนท้ายเพียงครั้งเดียว แล้วเอนจินเค้าโครงจะเรนเดอร์ส่วนเหล่านี้ในทุกหน้า รวมถึงหน้าที่เกิดจากการแบ่งหน้าอัตโนมัติ ให้กำหนดข้อมูลก่อน addPage() ครั้งแรก ไม่จำเป็นต้องวาดส่วนหัวหรือส่วนท้ายในแต่ละหน้าด้วยตนเอง เรซิพีนี้อิงตาม examples/13-header-footer.php

การติดตั้ง

composer require nextpdf/core:^3

ไม่จำเป็นต้องใช้ส่วนขยายเสริมใด ๆ API สำหรับส่วนหัวและส่วนท้ายใน Layout concern มีความเสถียรมาตั้งแต่เวอร์ชัน 1.0.0 และทำงานบนเมทริกซ์ backport เวอร์ชัน 8.1–8.4

ภาพรวมเชิงแนวคิด

ส่วนหัวและส่วนท้ายเป็นองค์ประกอบประจำหน้า (page furniture) เอนจินเค้าโครงจะวาดส่วนเหล่านี้ในแถบบนและแถบล่างที่สงวนไว้ของแต่ละหน้าเมื่อ flush หน้านั้น setHeaderData() บันทึกเนื้อหา ส่วน setHeaderFont(), setHeaderMargin(), setFooterFont() และ setFooterMargin() กำหนดรูปแบบตัวอักษรและระยะห่างจากขอบหน้า setPrintHeader(false) และ setPrintFooter(false) ใช้ปิดองค์ประกอบประจำหน้าสำหรับเอกสารที่ไม่ต้องการใช้งาน

เรขาคณิตของส่วนหัวและส่วนท้ายวัดเทียบกับขอบเขตของหน้า พจนานุกรมออบเจกต์ของหน้า (ISO 32000-2 §7.7.3.3) กำหนดให้รายการ MediaBox เป็นขอบเขตของสื่อ และรายการ CropBox เป็นพื้นที่ที่มองเห็นได้ซึ่งหน้าถูกตัดให้อยู่ในขอบเขตนั้น หัวข้อ 14.11.2 กำหนดความหมายของขอบเขตหน้าเหล่านั้น ระยะขอบส่วนหัวที่กำหนดคือระยะเยื้องจากขอบเขตนั้น มาร์กของส่วนหัวและส่วนท้ายไม่ใช่ออบเจกต์แยกต่างหาก แต่เป็นส่วนหนึ่งของสตรีม Contents ของแต่ละหน้า และถูกปล่อยออกมาในแต่ละหน้า (§7.7.3.3)

ขอบเขต 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";

กรณีขอบเขตและข้อควรระวัง

กำหนดองค์ประกอบประจำหน้าก่อนหน้าแรก การเรียก setHeaderData() หลังจาก addPage() จะไม่วาดหน้าก่อนหน้าใหม่ ดังนั้นควรกำหนดค่าก่อน addPage() ครั้งแรก
ระยะขอบส่วนหัวกับระยะขอบบนของเนื้อหา ระยะขอบส่วนหัวคือระยะห่างของส่วนหัวจากขอบหน้า ระยะขอบนี้แยกจากระยะขอบบนของเนื้อหาหลัก ทั้งสองส่วนอาจซ้อนทับกันได้หากระยะขอบบนของเนื้อหาหลักเล็กกว่าแถบส่วนหัว ดังนั้นควรเผื่อพื้นที่ไว้
ระงับองค์ประกอบประจำหน้าในระดับเอกสาร ไม่ใช่ในระดับหน้า setPrintHeader(false) มีผลกับทั้งเอกสาร ไม่มีตัวเลือกเปิดปิดระดับหน้าที่มีมาในตัว สำหรับหน้าปกที่ไม่มีองค์ประกอบประจำหน้า ให้ใช้เอกสารแยกต่างหากหรือเลือกการจัดเค้าโครงอย่างจงใจ
พาธของโลโก้ อาร์กิวเมนต์ $logo ของ setHeaderData() เป็นพาธไฟล์ในเครื่อง ตัวโหลดรูปภาพจะปฏิเสธ URL scheme (ดูเรซิพีเกี่ยวกับรูปภาพ) ดังนั้นให้ใช้ไฟล์ในเครื่อง

ประสิทธิภาพ

การเรนเดอร์ส่วนหัวและส่วนท้ายทำงานในแต่ละหน้า ต้นทุนของการเรนเดอร์ขึ้นอยู่กับเนื้อหาขององค์ประกอบประจำหน้า (ข้อความเพียงไม่กี่ส่วน) ไม่ใช่ขนาดของเนื้อหาหลัก การเรนเดอร์เพิ่มภาระให้กับการ flush แต่ละหน้าน้อยมากจนแทบไม่มีนัยสำคัญ งบประมาณ 2000 ms / 64 MB รองรับเอกสารหลายร้อยหน้าที่มีองค์ประกอบประจำหน้าในทุกหน้า

หมายเหตุด้านความปลอดภัย

ชื่อเรื่องและคำอธิบายของส่วนหัวจะถูกเรนเดอร์เป็นข้อความในเอกสาร หากข้อมูลเหล่านี้มีข้อมูลที่ผู้ใช้ควบคุมได้ เช่น ชื่อ tenant ให้จำกัดความยาวและทำความสะอาดข้อมูลในแบบเดียวกับที่จัดการข้อความเนื้อหาหลัก เรซิพีนี้ไม่มีการแยกวิเคราะห์และไม่มีการเข้าถึงเครือข่าย

ความสอดคล้องตามมาตรฐาน

ข้อความระบุ	ข้อกำหนด	อนุมาตรา
`MediaBox` คือรายการในพจนานุกรมออบเจกต์ของหน้าที่กำหนดขอบเขตของสื่อในหน้า ซึ่งเป็นเกณฑ์ในการวัดเรขาคณิตของ header/footer	ISO 32000-2	§7.7.3.3
`CropBox` คือรายการในพจนานุกรมออบเจกต์ของหน้าซึ่งเป็นพื้นที่ที่มองเห็นได้ และหน้าถูกตัดให้อยู่ในขอบเขตนั้น	ISO 32000-2	§7.7.3.3
มาร์กของ header/footer เป็นส่วนหนึ่งของสตรีม `Contents` ของแต่ละหน้า	ISO 32000-2	§7.7.3.3

โปรไฟล์การทำซ้ำได้ — เชิงโครงสร้าง อะตอม /ID ใน trailer และ /CreationDate / /ModDate จะแตกต่างกันในแต่ละครั้งที่บันทึก harness จะตัดอะตอมเหล่านั้นออก แล้วเปรียบเทียบโครงสร้างที่ปรับมาตรฐานด้วย qpdf เรซิพีนี้อธิบายว่า NextPDF สร้างโครงสร้างขึ้นมาอย่างไร แต่ไม่ได้ยืนยันความสอดคล้องตาม ISO 32000-2 ในลักษณะการอ้างแบบครอบคลุมทั้งหมด

บริบทเชิงพาณิชย์

ไม่เกี่ยวข้อง ส่วนหัวและส่วนท้ายแบบทำซ้ำเป็นความสามารถของ Core และไม่มีการจำกัดด้วย Premium