Table of contents — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này là tài liệu tham chiếu ở cấp hợp đồng cho module NextPDF Pro Toc, NextPDF\Pro\Toc. AutoTocCollector quét HTML để tìm các tiêu đề H1–H6 và phát ra các value object TocHeading. AutoTocRenderer phân trang các tiêu đề đó và render mỗi trang TOC thành các toán tử content-stream của PDF. AutoTocConfig là cấu hình render bất biến. Số trang do bên gọi cung cấp hoặc là các giá trị giữ chỗ tuần tự; module không phân giải các tham chiếu chéo trực tiếp của tài liệu. Trang này nêu API công khai, hợp đồng hành vi có thể quan sát, và các chế độ lỗi. Phần thiết lập theo tác vụ và các mẫu nằm ở trang năng lực Table of contents.

Tính khả dụng & cấp phép

Năng lực này đi kèm trong NextPDF Pro (nextpdf/pro) và kích hoạt cùng một license envelope cấp Pro. Một triển khai không có quyền đó sẽ không nạp các class của năng lực. So sánh các phiên bản và lấy giấy phép.

Không có cờ năng lực lúc chạy nào kiểm soát module này. Các class Toc có thể dùng bất cứ khi nào nextpdf/pro được cài đặt và cấp phép.

Bề mặt API công khai

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc lỗi với	Ghi chú
AutoTocCollector::__construct()	int $maxDepth = 6	Kẹp độ sâu vào khoảng 1–6	—	—	Thực thể tích lũy các tiêu đề đã thu thập
AutoTocCollector::extract()	string $html, int $maxDepth = 6	Khởi tạo, quét, và trả về các tiêu đề trong một lệnh gọi	list<TocHeading>	—	Đường tắt tĩnh
AutoTocCollector::scan()	string $html	Khớp H1–H6, tách bỏ markup, giải mã thực thể, gộp khoảng trắng, nối thêm các tiêu đề không rỗng	—	—	Thay đổi trạng thái nội bộ
AutoTocCollector::assignSequentialPages()	int $startPage = 1	Tăng trang tại mỗi tiêu đề cấp 0 sau tiêu đề đầu tiên	list<TocHeading>	—	Chỉ đánh số giữ chỗ
AutoTocCollector::assignPageNumbers()	array<int,int> $pageMap	Áp dụng một bản đồ chỉ-mục-tới-trang; các chỉ mục không được ánh xạ giữ trang hiện tại của chúng	list<TocHeading>	—	Trang thực do bên gọi cung cấp
AutoTocCollector::getHeadings()	—	Trả về các tiêu đề đã thu thập	list<TocHeading>	—	—
AutoTocCollector::count()	—	Số lượng tiêu đề đã thu thập	int	—	—
AutoTocCollector::reset()	—	Xóa các tiêu đề đã thu thập	—	—	Tái sử dụng collector qua các lần quét
AutoTocRenderer::render()	list<TocHeading> $headings, ?AutoTocConfig $config = null	Lọc theo độ sâu, phân trang, phát ra một content stream cho mỗi trang	list<string>	—	Trả về [] khi mọi tiêu đề đều bị lọc bỏ
AutoTocConfig::__construct()	14 tham số có kiểu (title, depth, fonts, spacing, margins, colors, page size)	Bộ mang cấu hình bất biến	—	—	Readonly; màu ChartColor mặc định là đen
AutoTocConfig::default(), ::landscape(), ::letter()	—	Các preset A4 dọc, A4 ngang, và US Letter	self	—	Factory tĩnh
AutoTocConfig::withTitle(), ::withMaxDepth(), ::withFontSize(), ::withDotLeader(), ::withPageNumbers(), ::withIndentPerLevel()	mỗi hàm một giá trị	Trả về một thực thể mới với trường đã thay đổi; withMaxDepth() kẹp vào 1–6	self	—	Fluent, không biến đổi
AutoTocConfig::contentWidth()	—	pageWidth - 2 * leftMargin	float	—	Dẫn xuất
AutoTocConfig::lineSpacing()	—	fontSize * lineHeight	float	—	Dẫn xuất
AutoTocConfig::entriesPerPage()	—	max(1, floor((pageHeight - 2*topMargin - 2*titleFontSize) / lineSpacing))	int	—	Luôn ≥ 1
TocHeading::__construct()	string $title, int $level, ?int $pageNumber = null, float $y = 0.0	Value object tiêu đề bất biến	—	—	Readonly; cấp 0 = H1
TocHeading::withPageNumber(), ::withY(), ::withPosition()	số trang và/hoặc tọa độ Y	Trả về một thực thể mới với các trường vị trí đã thay đổi	self	—	Fluent, không biến đổi
TocHeading::hasPageNumber()	—	True khi một số trang được gán	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

Hợp đồng hành vi

Thu thập

AutoTocCollector::scan() khớp <h1>–<h6> bằng một mẫu có giới hạn (không phân biệt hoa thường, dot-matches-newline) đòi hỏi một cặp thẻ mở và đóng cân bằng cùng cấp. Nội dung bên trong của mỗi lần khớp được tách bỏ thẻ, giải mã thực thể (ENT_QUOTES | ENT_HTML5, UTF-8), và gộp khoảng trắng. Các kết quả rỗng bị loại bỏ. level là số của thẻ trừ đi một, nên H1 là cấp 0. Một thẻ sâu hơn maxDepth sẽ bị bỏ qua. extract() là factory một-lệnh-gọi bao gồm khởi tạo, quét, và đọc lại.

Gán số trang

Tồn tại hai chiến lược tường minh, cả hai đều do bên gọi điều khiển.

• assignSequentialPages($startPage) tăng bộ đếm trang khi đạt tới một tiêu đề cấp 0 sau mục đầu tiên, rồi đóng dấu mọi tiêu đề.
• assignPageNumbers($pageMap) áp dụng một bản đồ chỉ-mục-tới-trang; một chỉ mục không được ánh xạ sẽ giữ số trang hiện có của nó.

Không chiến lược nào kiểm tra một tài liệu đã được bố cục.

Render và phân trang

AutoTocRenderer::render() giữ các tiêu đề có level thấp hơn maxDepth, trả về [] khi không còn gì sót lại, rồi chia phần còn lại thành các khối AutoTocConfig::entriesPerPage(). Mỗi khối trở thành một chuỗi content-stream. Với mỗi mục, thụt lề là leftMargin + level * indentPerLevel; cỡ chữ giảm 0.5 pt mỗi cấp và bị chặn dưới ở 6.0 pt; cấp 0 dùng khóa font đậm, các cấp sâu hơn dùng khóa font thường. Khi số trang được bật và có mặt, một dot leader tùy chọn lấp khoảng trống và số được canh phải. Tiêu đề và mọi chuỗi mục được hiển thị bằng toán tử Tj theo ISO 32000-2:2020 §9.4, và mỗi chuỗi được escape cho cú pháp chuỗi literal của PDF theo §7.3.4.2. HTML và cấu hình giống hệt nhau cho ra các tiêu đề và toán tử ổn định.

Trường hợp ngoại lệ & chế độ lỗi

• Markup tiêu đề méo dạng không được thu thập. Một <h2> chưa đóng không có </h2> tương ứng sẽ trượt mẫu cặp cân bằng và bị bỏ qua.
• Văn bản tiêu đề rỗng sau khi tách bỏ thẻ và cắt khoảng trắng sẽ bị loại bỏ.
• maxDepth được kẹp vào 1–6 tại cả constructor của collector và AutoTocConfig::withMaxDepth(); các giá trị ngoài khoảng được sửa lại, không bị từ chối.
• Số trang do bên gọi kiểm soát. Không có lượt bố cục nội bộ nào khám phá trang thực mà một tiêu đề rơi vào, nên module không thể phân giải các tham chiếu chéo trực tiếp.
• Module không phát sinh ngoại lệ nào. render() trả về một mảng rỗng khi mọi tiêu đề đều bị lọc bỏ theo độ sâu; nó không bao giờ ném lỗi trên đầu vào rỗng.
• Việc định cỡ suy về chặn dưới max(1, …), nên entriesPerPage() luôn ít nhất là 1 và phân trang luôn tiến triển.
• Renderer chỉ tạo ra các toán tử vẽ được. Bên gọi đặt các stream trả về lên các trang thực và cung cấp các tài nguyên /TocFont, /TocBoldFont, và /TocTitleFont.

Hành vi chế độ FIPS

Không có thao tác mã hóa nào xảy ra trong module này, nên không tồn tại hành vi đặc thù chế độ FIPS nào. Không có gì ở đây tiêu thụ tính ngẫu nhiên, băm, hay ký.

Tính phù hợp

Tuyên bố	Tiêu chuẩn	Điều khoản
Văn bản tiêu đề TOC và mục hiển thị bằng toán tử hiển thị văn bản Tj	ISO 32000-2:2020	§9.4
Các chuỗi phát ra được escape thành chuỗi literal của PDF, với dấu gạch chéo ngược được nhân đôi và dấu ngoặc đơn được escape	ISO 32000-2:2020	§7.3.4.2
Cây /Outlines của PDF hoặc các liên kết đích có tên	—	Không dựng (chỉ các toán tử content-stream)
Phân giải tham chiếu chéo trực tiếp của tài liệu	—	Không hỗ trợ (số trang do bên gọi cung cấp)

Tất cả các điều khoản đều được diễn giải lại; NextPDF không tái tạo văn bản quy phạm. Đây là các tuyên bố năng lực, không phải chứng nhận; NextPDF không nắm giữ chứng nhận nào và không cấp chứng nhận nào.

Ghi chú phát triển

• Tính khả dụng trong gói Pro: AutoTocCollector, AutoTocRenderer, AutoTocConfig, và TocHeading từ 1.9.0. Tất cả đều hiện hành trong nextpdf/pro 3.1.0.
• Các màu của AutoTocConfig là các giá trị NextPDF\Pro\Chart\ChartColor. Màu văn bản và tiêu đề mặc định là đen (0.0, 0.0, 0.0).
• Bắt đầu từ AutoTocConfig::default(), ::landscape(), hoặc ::letter(), rồi nối chuỗi các wither. Đối tượng là readonly, nên mỗi wither trả về một thực thể mới.
• Gán số trang thực bằng assignPageNumbers() từ lượt bố cục của riêng bạn; assignSequentialPages() chỉ cho ra các giá trị giữ chỗ.
• entriesPerPage(), lineSpacing(), và contentWidth() là các dẫn xuất thuần túy của cấu hình; gọi chúng để định cỡ trước bố cục trước khi render.
• getHeadings(), count(), và reset() đọc và xóa trạng thái tích lũy của collector giữa các lần quét.

Ranh giới xuất bản

Trang này chỉ ghi lại hành vi có thể quan sát từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, các class trợ giúp, các bảng cơ chế, các tên tệp runbook, và các tiền tố ticket nằm ngoài phạm vi.

Xem thêm

• Table of contents (năng lực) — cài đặt, khởi động nhanh, và các mẫu sản xuất.
• Merge — Tài liệu tham chiếu chuyên sâu
• Template — Tài liệu tham chiếu chuyên sâu