Dodawanie powtarzających się nagłówków i stopek

W skrócie

Skonfiguruj nagłówek (tytuł i opis) oraz stopkę tylko raz. Silnik układu renderuje je na każdej stronie, także na stronach utworzonych przez automatyczne podziały. Ustaw dane przed pierwszym wywołaniem addPage(). Nie musisz rysować nagłówka ani stopki osobno na każdej stronie. Ten przepis bazuje na examples/13-header-footer.php.

Instalacja

composer require nextpdf/core:^3

Nie jest wymagane żadne rozszerzenie opcjonalne. API nagłówka i stopki w obszarze Layout jest stabilne od wersji 1.0.0. Działa w macierzy backportu 8.1–8.4.

Przegląd koncepcyjny

Nagłówek i stopka to stałe elementy strony. Silnik układu rysuje je w zarezerwowanych pasach, górnym i dolnym, podczas finalizowania każdej strony. setHeaderData() zapisuje treść. setHeaderFont(), setHeaderMargin(), setFooterFont() oraz setFooterMargin() ustawiają typografię i odległość od krawędzi strony. setPrintHeader(false) oraz setPrintFooter(false) wyłączają te elementy w dokumentach, które ich nie potrzebują.

Geometria nagłówka i stopki jest mierzona względem granicy strony. Słownik obiektu strony (ISO 32000-2 §7.7.3.3) definiuje wpis MediaBox jako granicę nośnika, a wpis CropBox jako widoczny obszar, do którego strona jest przycinana. Sekcja 14.11.2 definiuje semantykę tych granic strony. Ustawiany margines nagłówka jest przesunięciem względem tej granicy. Elementy nagłówka i stopki nie są osobnymi obiektami; stanowią część strumienia Contents każdej strony i są emitowane dla każdej strony z osobna (§7.7.3.3).

Zakres API

Zakres API jest generowany z PHPDoc. Ten przepis korzysta z następujących metod:

setHeaderData(string $title = '', string $description = '', string $logo = '', float $logoWidth = 0): static — ustawia treść nagłówka.
setHeaderFont(string $family, float $size = 10): static / setFooterFont(string $family, float $size = 8): static — ustawiają typografię nagłówka i stopki.
setHeaderMargin(float $margin): static / setFooterMargin(float $margin): static — ustawiają odległość od krawędzi strony, w milimetrach.
setPrintHeader(bool $enabled): static / setPrintFooter(bool $enabled): static — przełączają te elementy.

Przykładowy kod — szybki start

<?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');

Przykładowy kod — wersja produkcyjna

Ten kompletny przykład, gotowy do uruchomienia w środowisku testowym, uwzględnia NEXTPDF_COOKBOOK_OUTPUT i nie koduje na stałe własnej entropii.

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

Przypadki brzegowe i pułapki

Ustaw elementy stałe przed pierwszą stroną. Wywołanie setHeaderData() po addPage() nie powoduje ponownego narysowania wcześniejszych stron, dlatego skonfiguruj je przed pierwszym addPage().
Margines nagłówka a górny margines treści. Margines nagłówka to odległość nagłówka od krawędzi strony. Jest niezależny od górnego marginesu treści. Oba mogą się nakładać, jeśli górny margines treści jest mniejszy niż pas nagłówka, dlatego pozostaw zapas miejsca.
Wyłączanie elementów stałych dotyczy dokumentu, a nie pojedynczej strony. setPrintHeader(false) dotyczy całego dokumentu. Nie ma wbudowanego przełącznika działającego na pojedynczej stronie. W przypadku strony tytułowej bez elementów stałych użyj osobnego dokumentu albo świadomie zaprojektuj układ.
Ścieżka logo. Argument $logo metody setHeaderData() to ścieżka do pliku lokalnego. Moduł wczytywania obrazów odrzuca schemat URL (zobacz przepis dotyczący obrazów), dlatego użyj pliku lokalnego.

Wydajność

Renderowanie nagłówka i stopki odbywa się osobno dla każdej strony. Jego koszt skaluje się wraz z treścią elementów stałych (kilka przebiegów tekstu), a nie z rozmiarem treści głównej. Dodaje pomijalny narzut podczas finalizowania każdej strony. Budżet 2000 ms / 64 MB obejmuje dokument liczący setki stron z elementami stałymi na każdej stronie.

Uwagi dotyczące bezpieczeństwa

Tytuł i opis nagłówka są renderowane jako tekst dokumentu. Jeśli zawierają dane kontrolowane przez użytkownika, takie jak nazwa najemcy, ogranicz ich długość i oczyszczaj je tak samo jak treść główną. Kod w tym przepisie nie wykonuje żadnego parsowania ani dostępu do sieci.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula
Wpis `MediaBox` w słowniku obiektu strony definiuje granicę nośnika strony, względem której mierzona jest geometria header/footer.	ISO 32000-2	§7.7.3.3
Wpis `CropBox` w słowniku obiektu strony to widoczny obszar, do którego strona jest przycinana.	ISO 32000-2	§7.7.3.3
Oznaczenia header/footer stanowią część strumienia `Contents` każdej strony.	ISO 32000-2	§7.7.3.3

Profil odtwarzalności — strukturalny. Atomy /ID w zwiastunie oraz /CreationDate / /ModDate zmieniają się przy każdym zapisie. Środowisko testowe usuwa te atomy, a następnie porównuje strukturę znormalizowaną przez qpdf. Ten przepis opisuje, jak NextPDF tworzy tę strukturę. Nie stanowi ogólnego zapewnienia zgodności z ISO 32000-2.

Kontekst komercyjny

Nie dotyczy. Powtarzające się nagłówki i stopki to funkcja Core, bez wymogu Premium.