Table of contents — เอกสารอ้างอิงเชิงลึก

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

หน้านี้เป็นเอกสารอ้างอิงระดับสัญญาสำหรับโมดูล NextPDF Pro Toc คือ NextPDF\Pro\Toc โดย AutoTocCollector สแกน HTML เพื่อหาหัวข้อ H1–H6 และปล่อย ออกมาเป็น value object TocHeading ส่วน AutoTocRenderer แบ่งหน้าหัวข้อเหล่านั้น และเรนเดอร์แต่ละหน้าของ TOC เป็นตัวดำเนินการ content-stream ของ PDF และ AutoTocConfig คือการกำหนดค่าการเรนเดอร์แบบไม่เปลี่ยนแปลง หมายเลขหน้ามาจาก ผู้เรียกใช้หรือเป็นตัวยึดตำแหน่งแบบเรียงลำดับ โมดูลไม่ resolve การอ้างอิงข้ามใน เอกสารแบบสด หน้านี้ระบุ public API สัญญาพฤติกรรมที่สังเกตได้ และโหมดความล้มเหลว การตั้งค่าเชิงงานและตัวอย่างอยู่ที่ หน้าความสามารถ Table of contents

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

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

ไม่มีแฟล็กความสามารถในขณะรันไทม์ที่จำกัดสิทธิ์โมดูลนี้ คลาส Toc ใช้งานได้เมื่อ nextpdf/pro ถูกติดตั้งและมีใบอนุญาตแล้ว

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

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
AutoTocCollector::__construct()	int $maxDepth = 6	หนีบความลึกให้อยู่ในช่วง 1–6	—	—	อินสแตนซ์สะสมหัวข้อที่เก็บได้
AutoTocCollector::extract()	string $html, int $maxDepth = 6	สร้าง สแกน และคืนหัวข้อในการเรียกครั้งเดียว	list<TocHeading>	—	ทางลัดแบบ static
AutoTocCollector::scan()	string $html	จับคู่ H1–H6 ถอดมาร์กอัป ถอดรหัส entity ยุบ whitespace และเพิ่มหัวข้อที่ไม่ว่างเข้าไป	—	—	เปลี่ยนแปลงสถานะภายใน
AutoTocCollector::assignSequentialPages()	int $startPage = 1	เลื่อนหน้าที่หัวข้อ level 0 แต่ละอันหลังจากอันแรก	list<TocHeading>	—	เป็นการกำหนดหมายเลขแบบตัวยึดตำแหน่งเท่านั้น
AutoTocCollector::assignPageNumbers()	array<int,int> $pageMap	ใช้การแมป index ไปยังหน้า index ที่ไม่ถูกแมปจะคงหน้าปัจจุบันไว้	list<TocHeading>	—	หน้าจริงที่ผู้เรียกใช้กำหนด
AutoTocCollector::getHeadings()	—	คืนหัวข้อที่เก็บได้	list<TocHeading>	—	—
AutoTocCollector::count()	—	จำนวนหัวข้อที่เก็บได้	int	—	—
AutoTocCollector::reset()	—	ล้างหัวข้อที่เก็บได้	—	—	นำ collector กลับมาใช้ซ้ำข้ามการสแกน
AutoTocRenderer::render()	list<TocHeading> $headings, ?AutoTocConfig $config = null	กรองตามความลึก แบ่งหน้า และปล่อย content stream หนึ่งชุดต่อหน้า	list<string>	—	คืน [] เมื่อหัวข้อทุกอันถูกกรองออกหมด
AutoTocConfig::__construct()	พารามิเตอร์ที่มีชนิด 14 ตัว (title, depth, fonts, spacing, margins, colors, page size)	ตัวเก็บการกำหนดค่าแบบไม่เปลี่ยนแปลง	—	—	readonly สี ChartColor มีค่าเริ่มต้นเป็นสีดำ
AutoTocConfig::default(), ::landscape(), ::letter()	—	พรีเซ็ต A4 แนวตั้ง, A4 แนวนอน และ US Letter	self	—	static factory
AutoTocConfig::withTitle(), ::withMaxDepth(), ::withFontSize(), ::withDotLeader(), ::withPageNumbers(), ::withIndentPerLevel()	ค่าละหนึ่งตัว	คืนอินสแตนซ์ใหม่ที่เปลี่ยนฟิลด์นั้น withMaxDepth() หนีบให้อยู่ในช่วง 1–6	self	—	แบบ fluent ไม่เปลี่ยนแปลงตัวเดิม
AutoTocConfig::contentWidth()	—	pageWidth - 2 * leftMargin	float	—	ค่าที่คำนวณได้
AutoTocConfig::lineSpacing()	—	fontSize * lineHeight	float	—	ค่าที่คำนวณได้
AutoTocConfig::entriesPerPage()	—	max(1, floor((pageHeight - 2*topMargin - 2*titleFontSize) / lineSpacing))	int	—	≥ 1 เสมอ
TocHeading::__construct()	string $title, int $level, ?int $pageNumber = null, float $y = 0.0	value object หัวข้อแบบไม่เปลี่ยนแปลง	—	—	readonly level 0 = H1
TocHeading::withPageNumber(), ::withY(), ::withPosition()	หมายเลขหน้าและ/หรือพิกัด Y	คืนอินสแตนซ์ใหม่ที่เปลี่ยนฟิลด์ตำแหน่ง	self	—	แบบ fluent ไม่เปลี่ยนแปลงตัวเดิม
TocHeading::hasPageNumber()	—	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

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

การเก็บรวบรวม

AutoTocCollector::scan() จับคู่ <h1>–<h6> ด้วยรูปแบบที่มีขอบเขต (ไม่คำนึงถึงตัวพิมพ์ใหญ่เล็ก และ dot-matches-newline) ซึ่งต้องมีแท็กเปิดและปิด ระดับเดียวกันที่สมดุลกัน เนื้อหาภายในของแต่ละการจับคู่จะถูกถอดแท็ก ถอดรหัส entity (ENT_QUOTES | ENT_HTML5, UTF-8) และยุบ whitespace ผลลัพธ์ว่างจะถูกตัดทิ้ง level คือเลขแท็กลบหนึ่ง ดังนั้น H1 จึงเป็น level 0 แท็กที่ลึกกว่า maxDepth จะ ถูกข้าม extract() คือ factory แบบเรียกครั้งเดียวที่รวมการสร้าง สแกน และอ่านกลับ

การกำหนดหมายเลขหน้า

มีกลยุทธ์ที่ชัดเจนสองแบบ ทั้งคู่ขับเคลื่อนโดยผู้เรียกใช้

• assignSequentialPages($startPage) เลื่อนตัวนับหน้าเมื่อพบหัวข้อ level 0 หลังจากรายการแรก แล้วประทับให้ทุกหัวข้อ
• assignPageNumbers($pageMap) ใช้การแมป index ไปยังหน้า index ที่ไม่ถูกแมป จะคงหมายเลขหน้าเดิมไว้

ทั้งสองกลยุทธ์ไม่ตรวจสอบเอกสารที่จัดวางแล้ว

การเรนเดอร์และการแบ่งหน้า

AutoTocRenderer::render() เก็บหัวข้อที่มี level ต่ำกว่า maxDepth คืน [] เมื่อไม่มีหัวข้อใดเหลือรอด แล้วแบ่งส่วนที่เหลือออกเป็นก้อนละ AutoTocConfig::entriesPerPage() แต่ละก้อนกลายเป็นสตริง content-stream หนึ่งชุด สำหรับแต่ละรายการ การเยื้องคือ leftMargin + level * indentPerLevel ขนาดฟอนต์ ลดลง 0.5 pt ต่อระดับและมีค่าต่ำสุดที่ 6.0 pt โดย level 0 ใช้คีย์ฟอนต์ตัวหนา ระดับที่ลึกกว่าใช้คีย์ปกติ เมื่อเปิดใช้และมีหมายเลขหน้า dot leader ที่เลือกได้จะ เติมช่องว่างและจัดหมายเลขชิดขวา ชื่อเรื่องและสตริงของทุกรายการจะแสดงด้วยตัว ดำเนินการ Tj ตาม ISO 32000-2:2020 §9.4 และแต่ละสตริงจะถูก escape สำหรับ ไวยากรณ์ literal-string ของ PDF ตาม §7.3.4.2 HTML และการกำหนดค่าที่เหมือนกันให้ หัวข้อและตัวดำเนินการที่เสถียร

กรณีขอบและโหมดความล้มเหลว

• มาร์กอัปหัวข้อที่ผิดรูปแบบจะไม่ถูกเก็บรวบรวม <h2> ที่ไม่ปิดและไม่มี </h2> ที่จับคู่กันจะไม่ผ่านรูปแบบคู่ที่สมดุลและถูกข้าม
• ข้อความหัวข้อที่ว่างเปล่าหลังการถอดแท็กและตัดช่องว่างจะถูกตัดทิ้ง
• maxDepth ถูกหนีบให้อยู่ในช่วง 1–6 ทั้งที่ตัวสร้างของ collector และ AutoTocConfig::withMaxDepth() ค่าที่อยู่นอกช่วงจะถูกแก้ไข ไม่ใช่ปฏิเสธ
• หมายเลขหน้าถูกควบคุมโดยผู้เรียกใช้ ไม่มี layout pass ภายในที่ค้นพบหน้าจริงที่ หัวข้อตกลงไป ดังนั้นโมดูลจึงไม่สามารถ resolve การอ้างอิงข้ามแบบสดได้
• โมดูลไม่โยน exception ใด render() คืน array ว่างเมื่อหัวข้อทุกอันถูกกรองออก ด้วยความลึก และไม่เคยโยนกับอินพุตว่าง
• การกำหนดขนาดยุบลงไปที่ค่าต่ำสุด max(1, …) ดังนั้น entriesPerPage() จึงมี ค่าอย่างน้อย 1 เสมอ และการแบ่งหน้ามีความคืบหน้าเสมอ
• ตัวเรนเดอร์ผลิตเฉพาะตัวดำเนินการที่วาดได้เท่านั้น ผู้เรียกใช้เป็นผู้วางสตรีมที่ คืนมาลงบนหน้าจริงและจัดหาทรัพยากร /TocFont, /TocBoldFont และ /TocTitleFont

พฤติกรรมในโหมด FIPS

ไม่มีการดำเนินการเชิงการเข้ารหัสลับเกิดขึ้นในโมดูลนี้ จึงไม่มีพฤติกรรมเฉพาะของ โหมด FIPS ไม่มีสิ่งใดในที่นี้ใช้ความสุ่ม การแฮช หรือการลงนาม

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

ข้อกล่าวอ้าง	มาตรฐาน	ข้อ
ชื่อเรื่อง TOC และข้อความรายการแสดงด้วยตัวดำเนินการแสดงข้อความ Tj	ISO 32000-2:2020	§9.4
สตริงที่ปล่อยออกถูก escape เป็น literal string ของ PDF โดยเพิ่มแบ็กสแลชเป็นสองเท่าและ escape วงเล็บ	ISO 32000-2:2020	§7.3.4.2
tree /Outlines ของ PDF หรือลิงก์ named-destination	—	ไม่ได้สร้าง (ตัวดำเนินการ content-stream เท่านั้น)
การ resolve การอ้างอิงข้ามในเอกสารแบบสด	—	ไม่รองรับ (หมายเลขหน้าที่ผู้เรียกใช้กำหนด)

ข้อทั้งหมดเป็นการถอดความ NextPDF ไม่ทำซ้ำข้อความเชิงบรรทัดฐาน ข้อความเหล่านี้เป็น การระบุความสามารถ ไม่ใช่การรับรอง NextPDF ไม่ถือการรับรองใดและไม่มอบการรับรองใด

หมายเหตุการพัฒนา

• การมีให้ใช้ภายในแพ็กเกจ Pro: AutoTocCollector, AutoTocRenderer, AutoTocConfig และ TocHeading มีมาตั้งแต่ 1.9.0 ทั้งหมดยังเป็นเวอร์ชัน ปัจจุบันใน nextpdf/pro 3.1.0
• สีของ AutoTocConfig เป็นค่า NextPDF\Pro\Chart\ChartColor สีข้อความและ สีชื่อเรื่องเริ่มต้นเป็นสีดำ (0.0, 0.0, 0.0)
• เริ่มจาก AutoTocConfig::default(), ::landscape() หรือ ::letter() แล้ว เชน wither ต่อกัน ออบเจกต์เป็น readonly ดังนั้นแต่ละ wither จึงคืนอินสแตนซ์ใหม่
• กำหนดหมายเลขหน้าจริงด้วย assignPageNumbers() จาก layout pass ของคุณเอง assignSequentialPages() ให้เพียงตัวยึดตำแหน่งเท่านั้น
• entriesPerPage(), lineSpacing() และ contentWidth() เป็นการคำนวณล้วนๆ จากการกำหนดค่า เรียกใช้เพื่อกำหนดขนาดเลย์เอาต์ล่วงหน้าก่อนการเรนเดอร์
• getHeadings(), count() และ reset() อ่านและล้างสถานะสะสมของ collector ระหว่างการสแกน

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

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

ดูเพิ่มเติม

• Table of contents (ความสามารถ) — การติดตั้ง เริ่มต้นอย่างรวดเร็ว และตัวอย่างระดับโปรดักชัน
• Merge — เอกสารอ้างอิงเชิงลึก
• Template — เอกสารอ้างอิงเชิงลึก