İçindekiler — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF Pro Toc modülü NextPDF\Pro\Toc için sözleşme düzeyinde başvurudur. AutoTocCollector, HTML’i H1–H6 başlıkları için tarar ve TocHeading değer nesneleri yayar. AutoTocRenderer, bu başlıkları sayfalandırır ve her TOC sayfasını PDF içerik akışı işleçleri olarak işler. AutoTocConfig, değişmez işleme yapılandırmasıdır. Sayfa numaraları çağıran tarafından sağlanır veya sıralı yer tutuculardır; modül, canlı belge çapraz başvurularını çözmez. Bu sayfa; genel API’yi, gözlemlenebilir davranış sözleşmesini ve hata modlarını belirtir. Göreve yönelik kurulum ve örnekler İçindekiler yetenek sayfasında yer alır.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) içinde gelir ve bir Pro katmanlı lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Bu modülü hiçbir çalışma zamanı yetenek bayrağı kapılamaz. Toc sınıfları, nextpdf/pro kurulu ve lisanslı olduğunda kullanılabilir.

Genel API yüzeyi

Simge	Parametreler	Varsayılan davranış	Döndürür	Fırlatır veya şununla başarısız olur	Notlar
AutoTocCollector::__construct()	int $maxDepth = 6	Derinliği 1–6 aralığına sıkıştırır	—	—	Örnek, toplanan başlıkları biriktirir
AutoTocCollector::extract()	string $html, int $maxDepth = 6	Tek çağrıda oluşturur, tarar ve başlıkları döndürür	list<TocHeading>	—	Statik hızlı yol
AutoTocCollector::scan()	string $html	H1–H6 ile eşleşir, biçimlendirmeyi ayıklar, varlıkları çözer, boşluğu daraltır, boş olmayan başlıkları ekler	—	—	İç durumu değiştirir
AutoTocCollector::assignSequentialPages()	int $startPage = 1	İlkinden sonra her level-0 başlığında sayfayı ilerletir	list<TocHeading>	—	Yalnızca yer tutucu numaralandırma
AutoTocCollector::assignPageNumbers()	array<int,int> $pageMap	Bir dizin-sayfa eşlemesi uygular; eşlenmemiş dizinler geçerli sayfalarını korur	list<TocHeading>	—	Çağıran tarafından sağlanan gerçek sayfalar
AutoTocCollector::getHeadings()	—	Toplanan başlıkları döndürür	list<TocHeading>	—	—
AutoTocCollector::count()	—	Toplanan başlıkların sayısı	int	—	—
AutoTocCollector::reset()	—	Toplanan başlıkları temizler	—	—	Toplayıcıyı taramalar arasında yeniden kullanın
AutoTocRenderer::render()	list<TocHeading> $headings, ?AutoTocConfig $config = null	Derinliğe göre filtreler, sayfalandırır, sayfa başına bir içerik akışı yayar	list<string>	—	Her başlık filtrelenip çıkarıldığında [] döndürür
AutoTocConfig::__construct()	14 türlü parametre (başlık, derinlik, yazı tipleri, aralık, kenar boşlukları, renkler, sayfa boyutu)	Değişmez yapılandırma taşıyıcısı	—	—	Salt okunur; ChartColor renkleri varsayılan olarak siyahtır
AutoTocConfig::default(), ::landscape(), ::letter()	—	A4 dikey, A4 yatay ve US Letter ön ayarları	self	—	Statik fabrikalar
AutoTocConfig::withTitle(), ::withMaxDepth(), ::withFontSize(), ::withDotLeader(), ::withPageNumbers(), ::withIndentPerLevel()	her biri bir değer	Alan değiştirilmiş yeni bir örnek döndürür; withMaxDepth() 1–6 aralığına sıkıştırır	self	—	Akıcı, değiştirmeyen
AutoTocConfig::contentWidth()	—	pageWidth - 2 * leftMargin	float	—	Türetilmiş
AutoTocConfig::lineSpacing()	—	fontSize * lineHeight	float	—	Türetilmiş
AutoTocConfig::entriesPerPage()	—	max(1, floor((pageHeight - 2*topMargin - 2*titleFontSize) / lineSpacing))	int	—	Her zaman ≥ 1
TocHeading::__construct()	string $title, int $level, ?int $pageNumber = null, float $y = 0.0	Değişmez başlık değer nesnesi	—	—	Salt okunur; level 0 = H1
TocHeading::withPageNumber(), ::withY(), ::withPosition()	sayfa numarası ve/veya Y koordinatı	Konum alanları değiştirilmiş yeni bir örnek döndürür	self	—	Akıcı, değiştirmeyen
TocHeading::hasPageNumber()	—	Bir sayfa numarası atandığında true	bool	—	—

public function __construct(int $maxDepth = 6)

public static function extract(string $html, int $maxDepth = 6): array

public function scan(string $html): void

public function assignSequentialPages(int $startPage = 1): array

public function assignPageNumbers(array $pageMap): array

public static function render(
    array $headings,
    ?AutoTocConfig $config = null,
): array

public function __construct(
    public string $title = 'Table of Contents',
    public int $maxDepth = 6,
    public float $fontSize = 10.0,
    public float $titleFontSize = 16.0,
    public float $indentPerLevel = 15.0,
    public float $lineHeight = 1.6,
    public bool $showPageNumbers = true,
    public bool $showDotLeader = true,
    public ChartColor $textColor = new ChartColor(0.0, 0.0, 0.0),
    public ChartColor $titleColor = new ChartColor(0.0, 0.0, 0.0),
    public float $leftMargin = 40.0,
    public float $topMargin = 50.0,
    public float $pageWidth = 595.28,
    public float $pageHeight = 841.89,
)

public function entriesPerPage(): int

public function __construct(
    public string $title,
    public int $level,
    public ?int $pageNumber = null,
    public float $y = 0.0,
)

public function withPageNumber(int $pageNumber): self

public function hasPageNumber(): bool

Davranış sözleşmesi

Toplama

AutoTocCollector::scan(), aynı düzeyde dengeli bir açma ve kapama etiketi gerektiren sınırlı bir desenle (büyük/küçük harf duyarsız, nokta-yeni-satırı-eşler) <h1>–<h6> ile eşleşir. Her eşleşmenin iç içeriğinden etiketler ayıklanır, varlıklar çözülür (ENT_QUOTES | ENT_HTML5, UTF-8) ve boşluk daraltılır. Boş sonuçlar bırakılır. level, etiket numarasının bir eksiğidir, dolayısıyla H1, level 0’dır. maxDepth’ten daha derin bir etiket atlanır. extract(), oluşturma, tarama ve geri okuma üzerinde tek çağrılık fabrikadır.

Sayfa numarası ataması

İki açık strateji vardır; her ikisi de çağıran tarafından yürütülür.

• assignSequentialPages($startPage), ilk girdiden sonra bir level-0 başlığa ulaşıldığında sayfa sayacını ilerletir, ardından her başlığı damgalar.
• assignPageNumbers($pageMap), bir dizin-sayfa eşlemesi uygular; eşlenmemiş bir dizin, mevcut sayfa numarasını korur.

Hiçbir strateji, yerleşimi yapılmış bir belgeyi incelemez.

İşleme ve sayfalandırma

AutoTocRenderer::render(), level’i maxDepth’in altında olan başlıkları tutar, hiçbir şey hayatta kalmadığında [] döndürür, ardından kalanı AutoTocConfig::entriesPerPage() boyutunda parçalara böler. Her parça, bir içerik akışı dizesine dönüşür. Girdi başına girinti leftMargin + level * indentPerLevel’dir; yazı tipi boyutu düzey başına 0.5 pt azalır ve 6.0 pt’de tabanlanır; level 0 kalın yazı tipi anahtarını, daha derin düzeyler ise normal anahtarı kullanır. Sayfa numaraları etkin ve mevcut olduğunda, isteğe bağlı bir nokta kılavuzu boşluğu doldurur ve sayı sağa hizalanır. Başlık ve her girdi dizesi, ISO 32000-2:2020 §9.4 uyarınca Tj işleciyle gösterilir ve her dize, §7.3.4.2 uyarınca PDF değişmez dize söz dizimi için kaçışlanır. Aynı HTML ve yapılandırma, kararlı başlıklar ve işleçler üretir.

Uç durumlar ve hata modları

• Bozuk biçimlendirilmiş başlık biçimlendirmesi toplanmaz. Eşleşen bir </h2> içermeyen kapatılmamış bir <h2>, dengeli çift desenini geçemez ve atlanır.
• Etiket ayıklama ve kırpma sonrasında boş kalan başlık metni bırakılır.
• maxDepth, hem toplayıcı kurucusunda hem de AutoTocConfig::withMaxDepth()’te 1–6 aralığına sıkıştırılır; aralık dışı değerler reddedilmez, düzeltilir.
• Sayfa numaraları çağıran tarafından denetlenir. Bir başlığın düştüğü gerçek sayfayı keşfeden bir iç yerleşim geçişi yoktur, dolayısıyla modül canlı çapraz başvuruları çözemez.
• Modül hiçbir istisna oluşturmaz. render(), her başlık derinliğe göre filtrelenip çıkarıldığında boş bir dizi döndürür; boş girdide asla fırlatmaz.
• Boyutlandırma max(1, …) tabanına düşer, dolayısıyla entriesPerPage() her zaman en az 1’dir ve sayfalandırma her zaman ilerleme kaydeder.
• İşleyici yalnızca çizilebilir işleçler üretir. Çağıran, döndürülen akışları gerçek sayfalara yerleştirir ve /TocFont, /TocBoldFont ve /TocTitleFont kaynaklarını sağlar.

FIPS modu davranışı

Bu modülde hiçbir kriptografik işlem gerçekleşmez, dolayısıyla FIPS moduna özgü hiçbir davranış yoktur. Burada hiçbir şey rastgelelik, karma veya imzalama tüketmez.

Uygunluk

İddia	Standart	Madde
TOC başlığı ve girdi metni Tj metin gösterme işleciyle gösterilir	ISO 32000-2:2020	§9.4
Yayılan dizeler, ters eğik çizgi ikiye katlanarak ve parantezler kaçışlanarak PDF değişmez dizeleri olarak kaçışlanır	ISO 32000-2:2020	§7.3.4.2
PDF /Outlines ağacı veya adlandırılmış hedef bağlantıları	—	Oluşturulmadı (yalnızca içerik akışı işleçleri)
Canlı belge çapraz başvuru çözümü	—	Desteklenmiyor (çağıran tarafından sağlanan sayfa numaraları)

Tüm maddeler açımlanmıştır; NextPDF normatif metni yeniden üretmez. Bunlar sertifikalar değil, yetenek beyanlarıdır; NextPDF hiçbir sertifikaya sahip değildir ve hiçbiri vermez.

Geliştirme notları

• Pro paketi içindeki kullanılabilirlik: AutoTocCollector, AutoTocRenderer, AutoTocConfig ve TocHeading 1.9.0’dan beri. Tümü nextpdf/pro 3.1.0’da güncel.
• AutoTocConfig renkleri NextPDF\Pro\Chart\ChartColor değerleridir. Varsayılan metin ve başlık renkleri siyahtır (0.0, 0.0, 0.0).
• AutoTocConfig::default(), ::landscape() veya ::letter() ile başlayın, ardından wither’ları zincirleyin. Nesne salt okunur olduğundan, her wither yeni bir örnek döndürür.
• Gerçek sayfa numaralarını kendi yerleşim geçişinizden assignPageNumbers() ile atayın; assignSequentialPages() yalnızca yer tutucular üretir.
• entriesPerPage(), lineSpacing() ve contentWidth(), yapılandırmanın saf türevleridir; yerleşimi işlemeden önce boyutlandırmak için bunları çağırın.
• getHeadings(), count() ve reset(), toplayıcının biriken durumunu taramalar arasında okur ve temizler.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. İç ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve talep ön ekleri kapsam dışıdır.

Ayrıca bkz.

• İçindekiler (yetenek) — kurulum, hızlı başlangıç ve üretim örnekleri.
• Merge — Derinlemesine başvuru
• Template — Derinlemesine başvuru