Pro phiên bản

Mục lục

Tổng quan nhanh

NextPDF\Pro\Toc thu thập các tiêu đề H1–H6 từ HTML và render một mục lục nhiều cấp, đã phân trang, dưới dạng các toán tử content-stream của PDF. Số trang do bên gọi cấp (hoặc các placeholder 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.

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

Năng lực này có trong NextPDF Pro (nextpdf/pro) và được kích hoạt bằng một envelope giấy phép cấp Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực. Các lớp Toc được nạp bất cứ khi nào nextpdf/pro đã được cài đặt; không có cờ năng lực lúc chạy nào kiểm soát module. So sánh các phiên bản và lấy giấy phép.

Cài đặt

composer require nextpdf/pro:^3

Tổng quan khái niệm

Quy trình có hai pha:

Thu thập. AutoTocCollector::extract($html, maxDepth) quét HTML để tìm các thẻ <h1>–<h6> cho đến giới hạn độ sâu, tách bỏ markup bên trong, giải mã thực thể (entity), chuẩn hóa khoảng trắng, và phát ra các value object TocHeading (cấp 0 = H1). Nó có thể gán số trang tuần tự hoặc áp dụng một bản đồ chỉ-mục-tới-trang do bên gọi cấp.
Render. AutoTocRenderer::render($headings, $config) tạo ra một chuỗi content-stream PDF cho mỗi trang TOC, với thụt lề theo cấp, dấu chấm dẫn (dot leader) tùy chọn, và số trang tùy chọn. Mỗi dòng hiển thị được phát ra dưới dạng một thao tác hiển thị văn bản Tj theo ISO 32000-2:2020 §9.4.

AutoTocConfig là một value object bất biến, được cấu hình theo kiểu fluent, kiểm soát tiêu đề, độ sâu, phông chữ, giãn dòng, lề, màu, kích thước trang, và việc có hiển thị dấu chấm dẫn và số trang hay không.

Vì sao nó hoạt động theo cách này

Quyết định trọng yếu là module không bao giờ bịa ra một số trang mà nó không thể biết. Các trang đích thực phụ thuộc vào tài liệu đã bố cục cuối cùng, vốn do bên gọi sở hữu; một phỏng đoán sẽ trôi dạt âm thầm mỗi khi phân trang thay đổi. Vì vậy việc thu thập và việc render vẫn tách rời khỏi bố cục. AutoTocCollector phát ra các tiêu đề với trang null hoặc placeholder; số trang thật chỉ đến qua một bản đồ assignPageNumbers() do bên gọi cấp. Việc render sau đó tạo ra các toán tử content-stream thuần túy, để lại việc đặt trang cho bên gọi. Kết quả vẫn tất định và trung thực: module nêu rõ điều nó không biết thay vì bịa ra nó.

Bối cảnh thiết kế: Một API từ chối phỏng đoán.

Hợp đồng hành vi

Đầu vào. HTML (thu thập) và một danh sách TocHeading (render).
Đầu ra. list<TocHeading> từ việc thu thập; list<string> các toán tử content-stream của PDF (một cho mỗi trang TOC) từ việc render.
Số trang. Hoặc được gán tuần tự, được cấp qua một bản đồ chỉ-mục-tới-trang, hoặc để null. Module không tính các trang đích thực từ một tài liệu đã được bố cục; nó không phân giải các tham chiếu chéo.
Độ sâu. maxDepth được kẹp vào 1–6. Các tiêu đề sâu hơn độ sâu đã cấu hình sẽ bị bỏ qua.
Tính tất định. Với cùng một HTML và cấu hình, các tiêu đề được thu thập và các toán tử được render là ổn định.

Bề mặt API công khai

Kiểu	Loại	Thành viên chính
`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`

Mẫu mã — Bắt đầu nhanh

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

Mẫu mã — Sản phẩm

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

Trường hợp ngoại lệ & lưu ý

Văn bản tiêu đề rỗng (sau khi tách bỏ thẻ) sẽ bị bỏ qua.
maxDepth được kẹp vào 1–6 ở cả collector và config; các giá trị ngoài khoảng sẽ được hiệu chỉnh, chứ không bị từ chối.
Số trang là các placeholder trừ khi bên gọi cấp một bản đồ thật; module không chạy một lượt bố cục để khám phá các trang đích thực.
Bộ render phát ra các toán tử content-stream để đặt lên một trang; bên gọi chịu trách nhiệm thêm các trang đó vào tài liệu.

Hiệu năng

Việc thu thập là một lượt biểu thức chính quy trên HTML. Việc render tuyến tính theo số lượng tiêu đề, được phân trang bởi entriesPerPage(). Xem performance_budget.

Lưu ý bảo mật

HTML được quét bằng một biểu thức chính quy tiêu đề có giới hạn và việc tách bỏ thẻ; không có HTML nào được thực thi và không có tham chiếu bên ngoài nào được đi theo. Văn bản được render được escape theo cú pháp chuỗi của content-stream.

Tính phù hợp

Tuyên bố	Điều khoản đặc tả	Tình trạng
Các dòng TOC được phát ra dưới dạng các thao tác hiển thị văn bản `Tj`	ISO 32000-2:2020 §9.4	Đã kiểm chứng (bộ unit)
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 cấp)

Phương án dự phòng / thay thế của Core

Không có bộ tạo TOC nào trong Core. HTML nguồn của tiêu đề thường đến từ pipeline HTML của Core. Xem /modules/core/html/.

Lưu ý về ranh giới Enterprise

Module này thu thập các tiêu đề và render các toán tử TOC. Nó không thực hiện việc phân giải tham chiếu chéo trên toàn tài liệu, tạo chỉ mục, hay đồng bộ cây bookmark; những vấn đề đó nằm ngoài phạm vi.

Ranh giới xuất bản

Trang này chỉ ghi lại hành vi quan sát được 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ộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook, và tiền tố ticket nằm ngoài phạm vi.