Daftar isi — Referensi Mendalam

Sekilas pandang

Halaman ini adalah referensi tingkat-kontrak untuk modul NextPDF Pro Toc, NextPDF\Pro\Toc. AutoTocCollector memindai HTML untuk heading H1–H6 dan memancarkan objek nilai TocHeading. AutoTocRenderer mempaginasi heading tersebut dan merender setiap halaman TOC sebagai operator content-stream PDF. AutoTocConfig adalah konfigurasi rendering yang imutabel. Nomor halaman disuplai pemanggil atau berupa placeholder berurutan; modul ini tidak menyelesaikan referensi-silang dokumen langsung. Halaman ini menyatakan API publik, kontrak perilaku yang dapat diamati, dan mode kegagalannya. Penyiapan berorientasi-tugas dan sampel tersedia di halaman kapabilitas Daftar isi.

Ketersediaan & lisensi

Kapabilitas ini dikirim dalam NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tier Pro. Sebuah deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada flag kapabilitas runtime yang menggerbang modul ini. Kelas-kelas Toc dapat digunakan kapan pun nextpdf/pro terpasang dan berlisensi.

Permukaan API publik

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
AutoTocCollector::__construct()	int $maxDepth = 6	Meng-clamp kedalaman ke rentang 1–6	—	—	Instance mengakumulasi heading yang dikumpulkan
AutoTocCollector::extract()	string $html, int $maxDepth = 6	Mengonstruksi, memindai, dan mengembalikan heading dalam satu panggilan	list<TocHeading>	—	Jalur cepat statis
AutoTocCollector::scan()	string $html	Mencocokkan H1–H6, meng-strip markup, men-decode entitas, menciutkan spasi-putih, menambahkan heading non-kosong	—	—	Memutasi state internal
AutoTocCollector::assignSequentialPages()	int $startPage = 1	Memajukan halaman pada setiap heading level-0 setelah yang pertama	list<TocHeading>	—	Hanya penomoran placeholder
AutoTocCollector::assignPageNumbers()	array<int,int> $pageMap	Menerapkan peta indeks-ke-halaman; indeks yang tidak terpeta mempertahankan halamannya saat ini	list<TocHeading>	—	Halaman nyata yang disuplai pemanggil
AutoTocCollector::getHeadings()	—	Mengembalikan heading yang dikumpulkan	list<TocHeading>	—	—
AutoTocCollector::count()	—	Jumlah heading yang dikumpulkan	int	—	—
AutoTocCollector::reset()	—	Membersihkan heading yang dikumpulkan	—	—	Gunakan ulang collector antar pemindaian
AutoTocRenderer::render()	list<TocHeading> $headings, ?AutoTocConfig $config = null	Menyaring berdasarkan kedalaman, mempaginasi, memancarkan satu content stream per halaman	list<string>	—	Mengembalikan [] ketika setiap heading tersaring keluar
AutoTocConfig::__construct()	14 param bertipe (title, depth, font, spacing, margin, warna, ukuran halaman)	Pembawa konfigurasi imutabel	—	—	Readonly; warna ChartColor default ke hitam
AutoTocConfig::default(), ::landscape(), ::letter()	—	Preset A4 portrait, A4 landscape, dan US Letter	self	—	Factory statis
AutoTocConfig::withTitle(), ::withMaxDepth(), ::withFontSize(), ::withDotLeader(), ::withPageNumbers(), ::withIndentPerLevel()	satu nilai masing-masing	Mengembalikan instance baru dengan field yang diubah; withMaxDepth() meng-clamp ke 1–6	self	—	Fluent, non-mutasi
AutoTocConfig::contentWidth()	—	pageWidth - 2 * leftMargin	float	—	Turunan
AutoTocConfig::lineSpacing()	—	fontSize * lineHeight	float	—	Turunan
AutoTocConfig::entriesPerPage()	—	max(1, floor((pageHeight - 2*topMargin - 2*titleFontSize) / lineSpacing))	int	—	Selalu ≥ 1
TocHeading::__construct()	string $title, int $level, ?int $pageNumber = null, float $y = 0.0	Objek nilai heading imutabel	—	—	Readonly; level 0 = H1
TocHeading::withPageNumber(), ::withY(), ::withPosition()	nomor halaman dan/atau koordinat Y	Mengembalikan instance baru dengan field posisi yang diubah	self	—	Fluent, non-mutasi
TocHeading::hasPageNumber()	—	True ketika sebuah nomor halaman ditetapkan	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

Kontrak perilaku

Pengumpulan

AutoTocCollector::scan() mencocokkan <h1>–<h6> dengan pola terbatas (tanpa membedakan huruf besar-kecil, dot-matches-newline) yang membutuhkan tag buka dan tutup yang seimbang pada level yang sama. Konten dalam setiap kecocokan di-strip tag-nya, di-decode entitasnya (ENT_QUOTES | ENT_HTML5, UTF-8), dan spasi-putihnya diciutkan. Hasil kosong dibuang. level adalah nomor tag dikurangi satu, sehingga H1 adalah level 0. Tag yang lebih dalam dari maxDepth dilewati. extract() adalah factory satu-panggilan atas konstruksi, pemindaian, dan pembacaan-balik.

Penetapan nomor-halaman

Dua strategi eksplisit tersedia, keduanya digerakkan pemanggil.

• assignSequentialPages($startPage) memajukan penghitung halaman ketika sebuah heading level-0 tercapai setelah entri pertama, lalu menstempel setiap heading.
• assignPageNumbers($pageMap) menerapkan peta indeks-ke-halaman; indeks yang tidak terpeta mempertahankan nomor halamannya yang ada.

Tidak satu pun strategi memeriksa dokumen yang telah ditata letak.

Rendering dan paginasi

AutoTocRenderer::render() mempertahankan heading yang level-nya di bawah maxDepth, mengembalikan [] ketika tidak ada yang tersisa, lalu memecah sisanya menjadi potongan-potongan sebesar AutoTocConfig::entriesPerPage(). Setiap potongan menjadi satu string content-stream. Per entri, indentasi adalah leftMargin + level * indentPerLevel; ukuran font berkurang 0.5 pt per level dan dibatasi minimum pada 6.0 pt; level 0 menggunakan key font bold, level yang lebih dalam menggunakan key reguler. Ketika nomor halaman diaktifkan dan tersedia, sebuah dot leader opsional mengisi celah dan nomornya diratakan ke kanan. Judul dan setiap string entri ditampilkan dengan operator Tj sesuai ISO 32000-2:2020 §9.4, dan setiap string di-escape untuk sintaks literal-string PDF sesuai §7.3.4.2. HTML dan konfigurasi yang identik menghasilkan heading dan operator yang stabil.

Kasus tepi & mode kegagalan

• Markup heading yang malformasi tidak dikumpulkan. Sebuah <h2> yang tidak tertutup tanpa </h2> yang cocok gagal memenuhi pola pasangan-seimbang dan dilewati.
• Teks heading yang kosong setelah tag di-strip dan di-trim akan dibuang.
• maxDepth di-clamp ke 1–6 baik pada konstruktor collector maupun AutoTocConfig::withMaxDepth(); nilai di luar rentang dikoreksi, bukan ditolak.
• Nomor halaman dikendalikan pemanggil. Tidak ada lintasan tata letak internal yang menemukan halaman nyata tempat sebuah heading mendarat, sehingga modul tidak dapat menyelesaikan referensi-silang langsung.
• Modul ini tidak memunculkan exception. render() mengembalikan array kosong ketika setiap heading tersaring keluar berdasarkan kedalaman; ia tidak pernah melempar pada input kosong.
• Pengukuran menciut ke batas bawah max(1, …), sehingga entriesPerPage() selalu setidaknya 1 dan paginasi selalu membuat kemajuan.
• Renderer hanya memproduksi operator yang dapat digambar. Pemanggil menempatkan stream yang dikembalikan pada halaman nyata dan menyuplai resource /TocFont, /TocBoldFont, dan /TocTitleFont.

Perilaku mode FIPS

Tidak ada operasi kriptografis yang terjadi pada modul ini, sehingga tidak ada perilaku spesifik mode FIPS. Tidak ada apa pun di sini yang mengonsumsi keacakan, hashing, atau penandatanganan.

Kesesuaian

Klaim	Standar	Klausa
Judul TOC dan teks entri ditampilkan dengan operator text-showing Tj	ISO 32000-2:2020	§9.4
String yang dipancarkan di-escape sebagai literal string PDF, dengan backslash digandakan dan tanda kurung di-escape	ISO 32000-2:2020	§7.3.4.2
Pohon /Outlines PDF atau tautan named-destination	—	Tidak dibangun (hanya operator content-stream)
Resolusi referensi-silang dokumen langsung	—	Tidak didukung (nomor halaman disuplai pemanggil)

Semua klausa diparafrasekan; NextPDF tidak mereproduksi teks normatif. Ini adalah pernyataan kapabilitas, bukan sertifikasi; NextPDF tidak memegang sertifikasi apa pun dan tidak memberikannya.

Catatan pengembangan

• Ketersediaan di dalam paket Pro: AutoTocCollector, AutoTocRenderer, AutoTocConfig, dan TocHeading sejak 1.9.0. Semuanya terkini di nextpdf/pro 3.1.0.
• Warna AutoTocConfig adalah nilai NextPDF\Pro\Chart\ChartColor. Warna teks dan judul default berwarna hitam (0.0, 0.0, 0.0).
• Mulailah dari AutoTocConfig::default(), ::landscape(), atau ::letter(), lalu rantaikan wither. Objeknya readonly, sehingga setiap wither mengembalikan instance baru.
• Tetapkan nomor halaman nyata dengan assignPageNumbers() dari lintasan tata letak Anda sendiri; assignSequentialPages() hanya menghasilkan placeholder.
• entriesPerPage(), lineSpacing(), dan contentWidth() adalah turunan murni dari konfigurasi; panggil keduanya untuk mengukur tata letak sebelum rendering.
• getHeadings(), count(), dan reset() membaca dan membersihkan state terakumulasi collector antar pemindaian.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama file runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Daftar isi (kapabilitas) — instalasi, mulai cepat, dan sampel produksi.
• Merge — Referensi Mendalam
• Template — Referensi Mendalam