Yinelenen üst bilgiler ve alt bilgiler ekleyin

Bir bakışta

Bir üst bilgiyi (başlık ve açıklama) ve bir alt bilgiyi bir kez yapılandırın. Yerleşim motoru bunları, otomatik sayfa sonlarıyla oluşturulan sayfalar dahil, her sayfada işler. Verileri ilk addPage() çağrısından önce ayarlayın. Üst bilgiyi veya alt bilgiyi her sayfaya tek tek çizmeniz gerekmez. Bu tarif examples/13-header-footer.php örneğini temel alır.

Kurulum

composer require nextpdf/core:^3

İsteğe bağlı hiçbir uzantı gerekmez. Layout concern’deki üst bilgi ve alt bilgi API’si, 1.0.0 sürümünden bu yana kararlıdır. 8.1–8.4 backport matrisinde çalışır.

Kavramsal genel bakış

Üst bilgi ve alt bilgi, sayfa donanımıdır. Yerleşim motoru bunları, sayfayı boşaltırken her sayfanın ayrılmış üst ve alt bantlarına çizer. setHeaderData() içeriği kaydeder. setHeaderFont(), setHeaderMargin(), setFooterFont() ve setFooterMargin() yazı tipini ve sayfa kenarından uzaklığı ayarlar. setPrintHeader(false) ve setPrintFooter(false), buna ihtiyaç duymayan belgelerde donanımı kapatır.

Üst bilgi ve alt bilgi geometrisi, sayfa sınırına göre ölçülür. Sayfa nesne sözlüğü (ISO 32000-2 §7.7.3.3), MediaBox girdisini ortam sınırı, CropBox girdisini ise sayfanın kırpıldığı görünür bölge olarak tanımlar. Bölüm 14.11.2, bu sayfa sınırlarının anlamını açıklar. Ayarladığınız üst bilgi kenar boşluğu, bu sınırdan ölçülen göreli uzaklıktır. Üst bilgi ve alt bilgi işaretleri ayrı nesneler değildir; her sayfanın Contents akışının bir parçasıdır ve sayfa başına yazılır (§7.7.3.3).

API yüzeyi

API yüzeyi PHPDoc’tan oluşturulur. Bu tarif şu yöntemleri kullanır:

setHeaderData(string $title = '', string $description = '', string $logo = '', float $logoWidth = 0): static — üst bilgi içeriğini ayarlar.
setHeaderFont(string $family, float $size = 10): static / setFooterFont(string $family, float $size = 8): static — üst bilgi ve alt bilgi yazı tipini ayarlar.
setHeaderMargin(float $margin): static / setFooterMargin(float $margin): static — sayfa kenarından uzaklığı milimetre cinsinden ayarlar.
setPrintHeader(bool $enabled): static / setPrintFooter(bool $enabled): static — donanımı açar veya kapatır.

Kod örneği — hızlı başlangıç

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

Kod örneği — üretim

Bu eksiksiz, test koşumuna hazır örnek NEXTPDF_COOKBOOK_OUTPUT değişkenine uyar ve kendi entropisini sabitlemez.

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

Uç durumlar ve tuzaklar

Donanımı ilk sayfadan önce ayarlayın. setHeaderData() çağrısını addPage() çağrısından sonra yapmak, önceki sayfaların yeniden çizilmesini sağlamaz; bu nedenle bunu ilk addPage() çağrısından önce yapılandırın.
Üst bilgi kenar boşluğu ile içerik üst kenar boşluğu. Üst bilgi kenar boşluğu, üst bilginin sayfa kenarından uzaklığıdır. Gövdenin üst kenar boşluğundan bağımsızdır. Gövde üst kenar boşluğu üst bilgi bandından küçükse ikisi çakışabilir; bu nedenle yeterli boşluk bırakın.
Donanımı sayfa başına değil, belge başına kapatın. setPrintHeader(false) belgenin tamamına uygulanır. Sayfa başına yerleşik bir açma/kapama seçeneği yoktur. Donanımsız bir kapak sayfası için ayrı bir belge kullanın ya da bilinçli bir yerleşim tercihi yapın.
Logo yolu. $logo bağımsız değişkeni (setHeaderData() yöntemine verilir) yerel bir dosya yoludur. Görüntü yükleyici bir URL şemasını reddeder (resimler tarifine bakın); bu nedenle yerel bir dosya kullanın.

Performans

Üst bilgi ve alt bilgi işleme, sayfa başına çalışır. Maliyeti, gövde boyutuyla değil donanım içeriğiyle (birkaç metin dizisi) ölçeklenir. Her sayfa boşaltma işlemine ihmal edilebilir bir ek yük getirir. 2000 ms / 64 MB bütçesi, her sayfasında donanım bulunan yüzlerce sayfalık bir belgeyi kapsar.

Güvenlik notları

Üst bilgi başlığı ve açıklaması belge metni olarak işlenir. Bir kiracı adı gibi kullanıcı denetimli veriler içeriyorlarsa, uzunluğu sınırlayın ve gövde metniyle aynı kurallarla temizleyin. Bu tarif ayrıştırma yapmaz ve ağ erişimi gerçekleştirmez.

Uygunluk

İfade	Belirtim	Madde
`MediaBox` sayfa nesne sözlüğü girdisi, header/footer geometrisinin ölçüldüğü sayfa ortam sınırını tanımlar.	ISO 32000-2	§7.7.3.3
`CropBox` sayfa nesne sözlüğü girdisi, sayfanın kırpıldığı görünür bölgedir.	ISO 32000-2	§7.7.3.3
Header/footer işaretleri her sayfanın `Contents` akışının bir parçasıdır.	ISO 32000-2	§7.7.3.3

Yeniden üretilebilirlik profili — yapısal. Fragman /ID ile /CreationDate / /ModDate atomları her kayıt işleminde değişir. Test koşumu bu atomları kaldırır, ardından qpdf ile normalleştirilmiş yapıyı karşılaştırır. Bu tarif, NextPDF uygulamasının bu yapıyı nasıl ürettiğini açıklar; ISO 32000-2’ye genel uygunluk iddiasında bulunmaz.

Ticari bağlam

Geçerli değildir. Yinelenen üst bilgiler ve alt bilgiler bir Core yeteneğidir; Premium kısıtı yoktur.