Yerleşim: üst bilgiler, alt bilgiler, sütunlar, kitapçık, sayfa yöneticisi

Bir bakışta

Layout modülü, Document cephesinin arkasındaki sayfa yerleşimi motorlarını içerir: üst bilgiler, alt bilgiler, çok sütunlu yerleşim, semer dikişli kitapçık dizgisi ve yapısal sayfa işlemleri. Küçük ve kararlıdır: altı sınıfın tamamı @since 1.0.0.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Layout (src/Layout/, altı sınıf, @since 1.0.0), HasLayout kavramının altındaki motor katmanıdır. Uygulamanız cephe yöntemlerini Document üzerinde çağırır; trait, her çağrıyı bu motorlardan birine yönlendirir. Manifest, modülü standard risk ve internal kararlılık olarak işaretler; tek bağımlısı Core modülüdür. Sınıfları doğrudan oluşturarak değil, cephe üzerinden kullanın.

HeaderFooter, yinelenen üst bilgiyi ve alt bilgiyi işler. Her bant için başlık, açıklama, logo, yazı tipi, kenar boşluğu ve renk durumunu saklar. Portable Document Format (PDF) içerik akışı işleçlerini renderHeader() ve renderFooter() aracılığıyla istek üzerine üretir. Varsayılan alt bilgi, sağa hizalı bir "page / total" dizesi yazdırır. setHeaderCallback() ve setFooterCallback(), varsayılan yerleşimi çağıranın sağladığı bir kapanışla değiştirir. getHeaderContentHeight(), üst bilginin kapladığı dikey alanı bildirir; böylece sayfa gövdesi onun altından başlayabilir. Belge etiketli PDF kipindeyken, üst bilgi içeriği yapı ağacının dışında kaldığı için HasPages otomatik üst bilgiyi yukarı akışta bastırır.

ColumnLayout, çok sütunlu akışı yönetir. setEqualColumns(int $count, float $totalWidth, float $gap = 5), kullanılabilir genişliği eşit sütunlara böler. setColumnsArray(), açık ColumnDefinition konumlarını ve genişliklerini kabul eder. Bir sütun seçmek için selectColumn(), ilerlemek için ise nextColumn() kullanın. getCurrentColumnX() / getCurrentColumnWidth(), etkin sütunun geometrisini döndürür. Geçersiz bir sütun sayısı, negatif bir boşluk veya pozitif olmayan hesaplanmış sütun genişliği PageLayoutException oluşturur.

BookletLayout, semer dikişli (orta kıvrımlı) ciltleme için sayfaları yeniden sıralar. Bir kitapçık yaprağı dört sayfa yuvası tuttuğundan reorderPages() sayfa listesini dördün katına tamamlar, ardından sayfaları dıştan içe dizer; böylece katlanıp zımbalanan yapraklar sırayla okunur. getMarginAdjustments(), belirli bir konumda her kenar için iç (sırt) ve dış (kenar) boşluklarını döndürür. getSheetCount(), bir sayfa sayısının kaç çift taraflı yaprak gerektirdiğini bildirir. Yeniden sıralama yalnızca içerik yerleşimini değiştirir. Altta yatan PDF sayfa dizisi, belgedeki sayfaların sıralamasını tanımlayan sayfa ağacıyla tutarlı biçimde doğrusal kalır (ISO 32000-2 §7.7).

PageManager, içerik işlemeden ayrı yapısal sayfa işlemleri sağlar. movePage(), copyPage() ve deletePage(), bir PageData dizisi üzerinde başvuru yoluyla çalışır. Sayfa bölgeleri (addPageRegion(), isInRegion(), getRegionOffset()) yazma yapılmayacak bölgeler tanımlar. Sayfa grupları (startPageGroup(), getGroupPageNo()) bölüm başına sayfa numaralandırmayı destekler. PageRegion ve ColumnDefinition, bu motorların kullandığı iki değer taşıyıcısıdır. Writer modülü, ortaya çıkan sayfaları, Kids girdisinin bir sayfa ağacı düğümünün doğrudan alt öğelerine yapılan dolaylı başvurular dizisi olduğu bir sayfa ağacına serileştirir (ISO 32000-2 §7.7.3.2).

API yüzeyi

Simge	Tür	Kararlılık	Beri
HeaderFooter::setHeaderData(string, string, string, float): self	yöntem	kararlı	1.0.0
HeaderFooter::setHeaderFont(string, float): self / setHeaderMargin(float): self	yöntem	kararlı	1.0.0
HeaderFooter::setFooterFont(string, float): self / setFooterMargin(float): self	yöntem	kararlı	1.0.0
HeaderFooter::setHeaderCallback(Closure): self / setFooterCallback(Closure): self	yöntem	kararlı	1.0.0
HeaderFooter::getHeaderContentHeight(): float	yöntem	kararlı	1.0.0
HeaderFooter::renderHeader(float, float, float, float, int, int): string	yöntem	kararlı	1.0.0
HeaderFooter::renderFooter(float, float, float, float, int, int, string): string	yöntem	kararlı	1.0.0
ColumnLayout::setEqualColumns(int, float, float): self	yöntem	kararlı	1.0.0
ColumnLayout::setColumnsArray(array): self / resetColumns(): self	yöntem	kararlı	1.0.0
ColumnLayout::selectColumn(int): self / nextColumn(): bool	yöntem	kararlı	1.0.0
ColumnLayout::getCurrentColumnX(float): float / getCurrentColumnWidth(float): float	yöntem	kararlı	1.0.0
BookletLayout::setBooklet(bool, float, float): void	yöntem	kararlı	1.0.0
BookletLayout::reorderPages(array): array	yöntem	kararlı	1.0.0
BookletLayout::getMarginAdjustments(int): array{left: float, right: float}	yöntem	kararlı	1.0.0
BookletLayout::getSheetCount(int): int	yöntem	kararlı	1.0.0
PageManager::movePage(int, int, array): void / copyPage(int, array): void / deletePage(int, array): void	yöntem	kararlı	1.0.0
PageManager::addPageRegion(float, float, float, float): void / isInRegion(float, float): bool	yöntem	kararlı	1.0.0
PageManager::getRegionOffset(float, float, float, float): float	yöntem	kararlı	1.0.0
PageManager::startPageGroup(): void / getGroupPageNo(int): int	yöntem	kararlı	1.0.0
PageRegion / ColumnDefinition	değer taşıyıcısı	kararlı	1.0.0

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->setTitle('Header and Footer');

$doc->setHeaderData(
    title: 'NextPDF Example',
    description: 'Header and Footer Demonstration',
);
$doc->setHeaderFont('helvetica', 10);
$doc->setHeaderMargin(5);
$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->save(__DIR__ . '/output/13-header-footer.pdf');

Kaynak: examples/13-header-footer.php. Üst bilgi her addPage() çağrısında işlenir; alt bilgi ise sayfa boşaltıldığında işlenir.

Kod örneği — üretim

Bir alt bilgi geri çağrısı sayfa numarası metnini belirler ve sütun motoru iki sütunlu bir gövdeyi yönlendirir. Her iki motora da cephe üzerinden erişirsiniz.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Two-Column Report');

$doc->setFooterCallback(static function (Document $d): void {
    $d->setFont('helvetica', '', 8);
    $d->text(180.0, 285.0, 'Page ' . ($d->getPage() + 1));
});

$doc->addPage();
$doc->setEqualColumns(2, gap: 8);
$doc->selectColumn(0);
$doc->setFont('helvetica', '', 10);
$doc->multiCell(0, 6, 'Left column flows here.');
$doc->selectColumn(1);
$doc->multiCell(0, 6, 'Right column flows here.');

$doc->save(__DIR__ . '/output/two-column-report.pdf');

Kaynak: examples/13-header-footer.php dosyasından alınan örüntü.

Uç durumlar ve tuzaklar

• setEqualColumns(), 1’in altındaki bir sütun sayısını, negatif bir boşluğu veya hesaplanmış sütun genişliği pozitif olmayan herhangi bir yerleşimi reddeder. Bozulmuş bir yerleşim döndürmek yerine PageLayoutException oluşturur.
• selectColumn(), aralık dışı bir dizini yok sayar ve geçerli sütunu korur; geçersiz bir dizin için asla istisna oluşturmaz. nextColumn(), zaten son sütundayken false döndürür.
• BookletLayout::reorderPages(), son sayfanın boyutlarından kopyalanan boş sayfalarla dördün katına tamamlar. Boş bir sayfa listesi boş bir dizi döndürür. Yeniden sıralama yalnızca yerleşimi etkiler; movePage() dizinleri yine de mantıksal sırayı ifade eder.
• PageManager::movePage(), copyPage() ve deletePage(), aralık dışı bir dizin için sessizce hiçbir işlem yapmaz; isset() ile doğrular ve diziyi değiştirmeden döner. Eksik bir sayfa çağıran taraftaki bir hataysa dizini kendiniz doğrulayın.
• getHeaderContentHeight(), üst bilgi devre dışıyken ya da ne başlığı ne de açıklaması varken 0.0 döndürür. Sayfa gövdesi bu durumda üst kenar boşluğundan başlar.
• Etiketli PDF kipinde otomatik üst bilgi yukarı akışta bastırılır. Erişilebilir belgeler için yapı farkındalıklı bir yerleşim oluşturun.

Performans

Üst bilgi ve alt bilgi işleme, işleçleri etkin sayfa arabelleğine O(yerleşim içeriği) düzeyinde ekler; maliyet belge boyutuyla değil, yazılan başlık, açıklama ve ayırıcıyla orantılı olarak ölçeklenir. Sütun matematiği çağrı başına O(1) düzeyindedir. BookletLayout::reorderPages(), tek seferlik bir tamamlama geçişiyle sayfa sayısında O(n) düzeyindedir; dizgi döngüsü her tamamlanan yuvayı bir kez işler. PageManager bölge testleri nokta başına O(bölge sayısı) düzeyindedir ve sayfa işlemleri O(n) maliyetli dizi eklemeleridir. Bu motorlar belge boyunca sayfa başına durum tutmaz; bu nedenle uzun belgelerde bellek büyümesi eklemezler. Baskın bellek maliyeti, biriken içerik akışıdır ve bunu akış ve bellek kavramı ele alır. HyperText Markup Language (HTML) işlem hattının gecikme ve bellek bütçesi kapısı PERFORMANCE-BUDGETS belgesinde belgelenmiştir; HTML işleme yoluyla sınırlıdır ve bu yerleşim motorlarını doğrudan kapsamaz. 1500 ms / 64 MB’lik performance_budget, hızlı başlangıç için performans zarfıdır; çağrı başına bir sözleşme değildir.

Güvenlik notları

Bu motorlar, çağıranın sağladığı dizeleri ve logo yolunu kullanır. Logo yolu, dosyayı gömmeden önce doğrulayan görüntü motorundan geçer. renderHeader() ve renderFooter(), başlık, açıklama ve sayfa numarası metnini içerik akışına ulaşmadan önce merkezi PDF dize kaçış mekanizmasından geçirir; böylece çağıran metin sabit dize dil bilgisinin dışına çıkamaz. Bir üst bilgi veya alt bilgi geri çağrısı, çağıran kodunu belgenin geri kalanıyla aynı güven düzeyinde çalıştırır; okuduğu dış verileri buna göre değerlendirin. PageManager sayfa işlemleri, mevcut PageData öğesine yapılan başvuruları taşır; güvenilmeyen baytları ayrıştırmaz.

Uygunluk

İddia	Standart	Madde	Kanıt
Kitapçık çıktısı için sayfa yeniden sıralaması yalnızca yerleşimi değiştirir; sayfa ağacı yine de belgedeki sayfaların doğrusal sıralamasını tanımlar.	ISO 32000-2	§7.7
Serileştirilmiş sayfa ağacı düğümünün Kids girdisi, o düğümün doğrudan alt öğelerine yapılan dolaylı başvuruların bir dizisidir.	ISO 32000-2	§7.7.3.2

Tablo her maddeyi başka sözcüklerle ifade eder ve terimleri sabit tutar; normatif metni yeniden üretmez.

Ayrıca bkz.

• Core/HasLayout trait’i — yerleşim motorlarını bir araya getiren cephe kavramı.
• Core/HasPages trait’i — sütun matematiğinde kullanılan sayfa boyutu ve kenar boşlukları.
• Writer — yerleştirilen sayfaları serileştiren PDF nesne ve sayfa ağacı üreticisi.
• Akış ve bellek — yerleşim motorlarının neden sayfa başına durum tutmadığı ve belleğe bağlı işleme yolunun nasıl çalıştığı.
• HTML / akış kısıtlamaları (ADR-001) — tek geçişli akış kapsamının gerekçesi.