إضافة رؤوس صفحات وتذييلات متكررة

لمحة سريعة

اضبط رأسًا (عنوانًا ووصفًا) وتذييلًا مرة واحدة. يعرضهما محرك التخطيط في كل صفحة، بما في ذلك الصفحات الناتجة عن فواصل الصفحات التلقائية. عيّن البيانات قبل أول addPage(). لا ترسم الرأس أو التذييل يدويًا في كل صفحة. تستند هذه الوصفة إلى examples/13-header-footer.php.

التثبيت

composer require nextpdf/core:^3

لا يلزم أي امتداد اختياري. واجهة برمجة التطبيقات (⁨API⁩) الخاصة بالرأس والتذييل في سمة ⁨Layout⁩ مستقرة منذ 1.0.0. وتعمل على مصفوفة النقل العكسي 8.1–8.4.

نظرة عامة مفاهيمية

الرأس والتذييل عنصران من عناصر تأثيث الصفحة. يرسمهما محرك التخطيط في الشريطين العلوي والسفلي المحجوزين في كل صفحة أثناء إفراغ الصفحة. يسجّل 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');

عيّنة شيفرة — للإنتاج

يلتزم هذا المثال الكامل الجاهز للتشغيل بقيمة منصة الاختبار 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⁩ (راجع وصفة الصور)، لذا استخدم ملفًا محليًا.

الأداء

يُنفَّذ عرض الرأس والتذييل لكل صفحة. تتناسب كلفته مع محتوى عناصر التأثيث (بضعة مقاطع نصية)، لا مع حجم المتن. ويضيف عبئًا لا يُذكر إلى كل عملية إفراغ صفحة. تغطي ميزانية 2000 ⁨ms⁩ / 64 ⁨MB⁩ مستندًا من عدة مئات من الصفحات مع عناصر تأثيث في كل صفحة.

ملاحظات أمنية

يُعرض عنوان الرأس ووصفه بوصفهما نصًا في المستند. إذا تضمّنا بيانات يتحكم فيها المستخدم، مثل اسم مستأجر، فحدّد الطول ونقِّ المُدخل بالطريقة نفسها التي تعالج بها نص المتن. لا تُجري هذه الوصفة أي تحليل ولا أي وصول إلى الشبكة.

المطابقة

العبارة	المواصفة	البند
يعرّف المُدخل `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 في المُذيّل وذرّتا /CreationDate / /ModDate مع كل عملية حفظ. تجرّد منصة الاختبار تلك الذرّات، ثم تقارن البنية المُطبَّعة بواسطة ⁨qpdf.⁩ تصف هذه الوصفة كيف يُنتج ⁨NextPDF⁩ البنية. ولا تؤكد المطابقة لـ ⁨ISO 32000-2⁩ بوصفها ادعاءً شاملًا.

السياق التجاري

لا ينطبق. الرؤوس والتذييلات المتكررة هي إمكانية في ⁨Core⁩، دون أي بوابة ⁨Premium.⁩