Pro รุ่น

สารบัญ

ภาพรวมโดยสรุป

NextPDF\Pro\Toc เก็บรวบรวมหัวข้อ H1–H6 จาก HTML และเรนเดอร์สารบัญหลายระดับ ที่แบ่งหน้าแล้วเป็นตัวดำเนินการ content-stream ของ PDF หมายเลขหน้า ถูกจัดหาโดยผู้เรียกใช้ (หรือ placeholder ตามลำดับ) โมดูลไม่ resolve cross-reference ของเอกสารแบบสด

ความพร้อมใช้งานและการอนุญาต

ความสามารถนี้มาพร้อมกับ NextPDF Pro (nextpdf/pro) และเปิดใช้งานด้วย license envelope ระดับ Pro การติดตั้งใช้งานที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ คลาส Toc จะโหลด เมื่อใดก็ตามที่ติดตั้ง nextpdf/pro ไม่มีแฟล็กความสามารถในขณะรันไทม์ที่จำกัดสิทธิ์ โมดูลนี้ เปรียบเทียบรุ่นและรับ license

การติดตั้ง

composer require nextpdf/pro:^3

ภาพรวมเชิงแนวคิด

เวิร์กโฟลว์มีสองเฟส:

Collection AutoTocCollector::extract($html, maxDepth) สแกน HTML หาแท็ก <h1>–<h6> จนถึงขีดจำกัดความลึก ถอดมาร์กอัปภายใน decode entity ทำให้ whitespace เป็นมาตรฐาน และ emit value object TocHeading (level 0 = H1) มันสามารถกำหนดหมายเลขหน้าตามลำดับหรือใช้ การแมป index ไปยังหน้าที่ผู้เรียกใช้จัดหา
Rendering AutoTocRenderer::render($headings, $config) ผลิตสตริง content-stream ของ PDF หนึ่งสตริงต่อหน้า TOC พร้อมการเยื้องต่อระดับ dot leader ที่เลือกได้ และหมายเลขหน้าที่เลือกได้ บรรทัดที่มองเห็นได้แต่ละบรรทัดถูก emit เป็นการดำเนินการแสดงข้อความ Tj ตาม ISO 32000-2:2020 §9.4

AutoTocConfig เป็น value object แบบ immutable ที่กำหนดค่าแบบ fluent ควบคุม ชื่อ ความลึก ฟอนต์ ระยะห่าง ขอบ สี ขนาดหน้า และว่าจะแสดง dot leader และหมายเลขหน้าหรือไม่

ทำไมจึงทำงานเช่นนี้

การตัดสินใจสำคัญคือโมดูลจะไม่สร้างหมายเลขหน้าที่มันไม่อาจรู้ได้ขึ้นมาเอง หน้าเป้าหมาย จริงขึ้นอยู่กับเอกสารที่จัดเค้าโครงเสร็จแล้วซึ่งเป็นของผู้เรียกใช้ การเดาจะคลาดเคลื่อน อย่างเงียบ ๆ เมื่อใดก็ตามที่การแบ่งหน้าเปลี่ยนไป ดังนั้น collection และ rendering จึงแยกออกจาก layout AutoTocCollector emit หัวข้อพร้อมหน้าที่เป็น null หรือ placeholder หมายเลขหน้าจริงมาถึงผ่านการแมป assignPageNumbers() ที่ผู้เรียกใช้จัดหาเท่านั้น จากนั้น rendering จะผลิตตัวดำเนินการ content-stream ธรรมดา โดยปล่อยการวางหน้าให้ผู้เรียกใช้ ผลลัพธ์ จึงยังคงเป็น deterministic และซื่อตรง คือโมดูลระบุสิ่งที่มันไม่รู้แทนที่จะกุมันขึ้นมา

พื้นหลังการออกแบบ: API ที่ปฏิเสธการเดา

สัญญาพฤติกรรม

Input HTML (collection) และรายการ TocHeading (rendering)
Output list<TocHeading> จาก collection และ list<string> ของตัวดำเนินการ PDF content-stream (หนึ่งรายการต่อหน้า TOC) จาก rendering
Page numbers อาจถูกกำหนดตามลำดับ จัดหาผ่าน การแมป index ไปยังหน้า หรือปล่อยเป็น null โมดูลไม่คำนวณหน้าเป้าหมาย จริงจากเอกสารที่จัดเค้าโครงแล้ว มันไม่ resolve cross-reference
Depth maxDepth ถูกหนีบให้อยู่ในช่วง 1–6 หัวข้อที่ลึกกว่า ความลึกที่กำหนดค่าไว้จะถูกข้าม
Determinism สำหรับ HTML และการกำหนดค่าที่เหมือนกัน หัวข้อที่เก็บรวบรวม และตัวดำเนินการที่เรนเดอร์จะเสถียร

พื้นผิว API สาธารณะ

Type	Kind	Key members
`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`

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

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

ตัวอย่างโค้ด — สำหรับใช้งานจริง

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

กรณีขอบและข้อควรระวัง

ข้อความหัวข้อที่ว่าง (หลังถอดแท็ก) จะถูกข้าม
maxDepth ถูกหนีบให้อยู่ในช่วง 1–6 ทั้งที่ collector และ config ค่าที่อยู่นอกช่วง จะถูกแก้ไข ไม่ใช่ถูกปฏิเสธ
หมายเลขหน้าเป็น placeholder เว้นแต่ผู้เรียกใช้จะจัดหาการแมปจริง โมดูลไม่รัน layout pass เพื่อค้นพบหน้าเป้าหมายจริง
ตัวเรนเดอร์ emit ตัวดำเนินการ content-stream เพื่อวางลงบนหน้า ผู้เรียกใช้มีหน้าที่รับผิดชอบในการเพิ่มหน้าเหล่านั้นเข้าในเอกสาร

ประสิทธิภาพ

Collection คือการ pass ด้วย regular-expression หนึ่งครั้งบน HTML การ Rendering เป็นเชิงเส้น ตามจำนวนหัวข้อ แบ่งหน้าด้วย entriesPerPage() ดู performance_budget

หมายเหตุด้านความปลอดภัย

HTML ถูกสแกนด้วย regular expression หัวข้อที่มีขอบเขตและการถอดแท็ก ไม่มี HTML ถูกรัน และไม่มีการอ้างอิงภายนอกใดถูกติดตาม ข้อความที่เรนเดอร์ถูก escape สำหรับไวยากรณ์สตริงของ content-stream

ความสอดคล้อง

Claim	Spec clause	Status
บรรทัด TOC ถูก emit เป็นการดำเนินการแสดงข้อความ `Tj`	ISO 32000-2:2020 §9.4	Verified (unit suite)
การ resolve cross-reference ของเอกสารแบบสด	—	Not supported (caller-supplied page numbers)

การถอยกลับไปใช้ Core / ทางเลือก

ไม่มีตัวสร้าง TOC ของ Core แหล่ง HTML ของหัวข้อมักมาจาก ไปป์ไลน์ HTML ของ Core ดู /modules/core/html/

หมายเหตุขอบเขต Enterprise

โมดูลนี้เก็บรวบรวมหัวข้อและเรนเดอร์ตัวดำเนินการ TOC มันไม่ทำการ resolve cross-reference ทั่วทั้งเอกสาร การสร้างดัชนี หรือ การ sync tree ของ bookmark ความกังวลเหล่านั้นอยู่นอกขอบเขต

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว public API ที่รองรับเท่านั้น path ของ namespace ภายใน คลาส helper ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต