Pro sürüm

İçindekiler tablosu

Bir bakışta

NextPDF\Pro\Toc, HTML’den H1–H6 başlıklarını toplar ve sayfalandırılmış, çok düzeyli bir içindekiler tablosunu PDF içerik akışı operatörleri olarak işler. Sayfa numaraları çağıran tarafından sağlanır (veya sıralı yer tutucular); modül, canlı belgedeki çapraz başvuruları çözmez.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile birlikte gelir ve bir Pro katmanı lisans zarfıyla etkinleşir. Bu yetkiye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Toc sınıfları, nextpdf/pro yüklü olduğunda her zaman yüklenir; hiçbir çalışma zamanı yetenek bayrağı modülü kapılamaz. Sürümleri karşılaştırın ve bir lisans edinin.

Kurulum

composer require nextpdf/pro:^3

Kavramsal genel bakış

İş akışının iki aşaması vardır:

Toplama. AutoTocCollector::extract($html, maxDepth), derinlik sınırına kadar <h1>–<h6> etiketleri için HTML’yi tarar, iç biçimlendirmeyi ayıklar, varlıkları çözer, boşluğu normalleştirir ve TocHeading değer nesneleri yayar (level 0 = H1). Sıralı sayfa numaraları atayabilir veya çağıranın sağladığı bir dizin-sayfa eşlemesini uygulayabilir.
İşleme. AutoTocRenderer::render($headings, $config), TOC sayfası başına bir PDF içerik akışı dizesi üretir; düzey başına girinti, isteğe bağlı nokta öncüleri ve isteğe bağlı sayfa numaralarıyla. Görünür her satır, ISO 32000-2:2020 §9.4 uyarınca bir Tj metin gösterme işlemi olarak yayılır.

AutoTocConfig; başlığı, derinliği, yazı tiplerini, aralığı, kenar boşluklarını, renkleri, sayfa boyutunu ve nokta öncülerinin ve sayfa numaralarının gösterilip gösterilmeyeceğini denetleyen, değişmez, akıcı biçimde yapılandırılan bir değer nesnesidir.

Neden bu şekilde çalışır

Yük taşıyan karar, modülün bilemeyeceği bir sayfa numarasını asla uydurmamasıdır. Gerçek hedef sayfalar, çağıranın sahip olduğu nihai yerleşimi yapılmış belgeye bağlıdır; bir tahmin, sayfalandırma her değiştiğinde sessizce kayar. Bu nedenle toplama ve işleme, yerleşimden ayrık kalır. AutoTocCollector, null veya yer tutucu sayfalara sahip başlıklar yayar; gerçek sayfa numaraları yalnızca çağıranın sağladığı bir assignPageNumbers() eşlemesi aracılığıyla gelir. İşleme ardından düz içerik akışı operatörleri üretir ve sayfa yerleşimini çağırana bırakır. Sonuç, belirlenimci ve dürüst kalır: modül, bilmediği şeyi uydurmak yerine bilmediğini belirtir.

Tasarım arka planı: Tahmin etmeyi reddeden bir API.

Davranış sözleşmesi

Giriş. HTML (toplama) ve bir TocHeading listesi (işleme).
Çıkış. Toplamadan list<TocHeading>; işlemeden (TOC sayfası başına bir tane) PDF içerik akışı operatörlerinin list<string> değeri.
Sayfa numaraları. Ya sıralı olarak atanır, bir dizin-sayfa eşlemesi aracılığıyla sağlanır ya da null bırakılır. Modül, yerleşimi yapılmış bir belgeden gerçek hedef sayfaları hesaplamaz; çapraz başvuruları çözmez.
Derinlik. maxDepth, 1–6 aralığına sıkıştırılır. Yapılandırılan derinlikten daha derin başlıklar atlanır.
Belirlenircilik. Özdeş HTML ve yapılandırma için, toplanan başlıklar ve işlenen operatörler kararlıdır.

Genel API yüzeyi

Tür	Çeşit	Temel üyeler
`NextPDF\Pro\Toc\AutoTocCollector`	`final class`	`static extract(string $html, int $maxDepth = 6): list<TocHeading>`, `scan(string $html): void`, `assignSequentialPages(int $startPage = 1): list<TocHeading>`, `assignPageNumbers(array $pageMap): list<TocHeading>`
`NextPDF\Pro\Toc\AutoTocRenderer`	`final class`	`static render(array $headings, ?AutoTocConfig $config = null): list<string>`
`NextPDF\Pro\Toc\AutoTocConfig`	`final readonly class`	`default()`, `landscape()`, `letter()`, `withTitle()`, `withMaxDepth()`, `withFontSize()`, `withDotLeader()`, `withPageNumbers()`, `withIndentPerLevel()`, `entriesPerPage(): int`
`NextPDF\Pro\Toc\TocHeading`	`final readonly class`	`string $title`, `int $level`, `?int $pageNumber`, `float $y`, `withPageNumber()`, `withPosition()`, `hasPageNumber(): bool`

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

<?php

declare(strict_types=1);

use NextPDF\Pro\Toc\AutoTocCollector;
use NextPDF\Pro\Toc\AutoTocRenderer;

$headings = AutoTocCollector::extract($html, maxDepth: 3);
$streams  = AutoTocRenderer::render($headings);

echo count($streams), " TOC page(s) of content-stream operators\n";

Kod örneği — üretim

<?php

declare(strict_types=1);

use NextPDF\Pro\Toc\AutoTocCollector;
use NextPDF\Pro\Toc\AutoTocConfig;
use NextPDF\Pro\Toc\AutoTocRenderer;

function buildToc(string $html, array $headingPageMap): array
{
    $collector = new AutoTocCollector(maxDepth: 4);
    $collector->scan($html);

    // Caller supplies real page numbers from its own layout pass.
    $headings = $collector->assignPageNumbers($headingPageMap);

    $config = AutoTocConfig::default()
        ->withTitle('Contents')
        ->withMaxDepth(4)
        ->withDotLeader(true)
        ->withPageNumbers(true);

    return AutoTocRenderer::render($headings, $config);
}

Uç durumlar ve tuzaklar

Boş başlık metni (etiket ayıklamadan sonra) atlanır.
maxDepth, hem toplayıcıda hem de yapılandırmada 1–6 aralığına sıkıştırılır; aralık dışı değerler reddedilmez, düzeltilir.
Çağıran gerçek bir eşleme sağlamadıkça sayfa numaraları yer tutucudur; modül, gerçek hedef sayfaları keşfetmek için bir yerleşim geçişi çalıştırmaz.
Oluşturucu, bir sayfaya yerleştirmek için içerik akışı operatörleri yayar; bu sayfaları belgeye ekleme sorumluluğu çağırana aittir.

Performans

Toplama, HTML üzerinde bir düzenli ifade geçişidir. İşleme, başlık sayısında doğrusaldır ve entriesPerPage() ile sayfalandırılır. performance_budget bölümüne bakın.

Güvenlik notları

HTML, sınırlı bir başlık düzenli ifadesi ve etiket ayıklamayla taranır; hiçbir HTML yürütülmez ve hiçbir harici başvuru izlenmez. İşlenen metin, içerik akışı dize söz dizimi için kaçışlanır.

Uygunluk

İddia	Belirtim kuralı	Durum
TOC satırları `Tj` metin gösterme işlemleri olarak yayılır	ISO 32000-2:2020 §9.4	Doğrulandı (birim süiti)
Canlı belge çapraz başvuru çözümü	—	Desteklenmiyor (çağıranın sağladığı sayfa numaraları)

Core yedeği / alternatifi

Bir Core TOC oluşturucusu yoktur. Başlık kaynağı HTML genellikle Core HTML işlem hattından gelir. /modules/core/html/ bölümüne bakın.

Enterprise sınır notu

Bu modül başlıkları toplar ve TOC operatörlerini işler. Belge çapında çapraz başvuru çözümü, dizin oluşturma veya yer imi ağacı eşitlemesi gerçekleştirmez; bu konular kapsam dışıdır.

Yayımlama sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilen davranışı ve desteklenen genel API yüzeyini belgeler. İç ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, çalıştırma kılavuzu dosya adları ve talep önekleri kapsam dışıdır.