Pro 에디션

Table of contents — 심층 참조

한눈에 보기

이 페이지는 NextPDF Pro Toc 모듈 NextPDF\Pro\Toc에 대한 계약 수준 참조입니다. AutoTocCollector는 HTML에서 H1–H6 제목을 스캔하고 TocHeading 값 객체를 방출합니다. AutoTocRenderer는 이 제목들을 페이지네이션하고 각 TOC 페이지를 PDF 콘텐츠 스트림 연산자로 렌더링합니다. AutoTocConfig는 불변 렌더링 구성입니다. 페이지 번호는 호출자가 제공하거나 순차적 플레이스홀더이며, 모듈은 라이브 문서 상호 참조를 해석하지 않습니다. 이 페이지는 공개 API, 관찰 가능한 동작 계약, 실패 모드를 명시합니다. 작업 중심 설정과 샘플은 목차 기능 페이지에 있습니다.

제공 여부 및 라이선싱

이 기능은 NextPDF Pro(nextpdf/pro)에 포함되어 있으며 Pro 등급 라이선스 엔벨로프로 활성화됩니다. 해당 권한이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

이 모듈을 게이팅하는 런타임 기능 플래그가 없습니다. Toc 클래스는 nextpdf/pro가 설치되고 라이선스가 부여되면 언제든 사용할 수 있습니다.

공개 API 표면

기호	매개변수	기본 동작	반환값	예외 또는 실패	비고
`AutoTocCollector::__construct()`	`int $maxDepth = 6`	깊이를 1–6 범위로 클램핑합니다	—	—	인스턴스가 수집된 제목을 누적합니다
`AutoTocCollector::extract()`	`string $html`, `int $maxDepth = 6`	한 번의 호출로 생성, 스캔, 제목 반환을 수행합니다	`list<TocHeading>`	—	정적 빠른 경로
`AutoTocCollector::scan()`	`string $html`	H1–H6을 매칭하고, 마크업을 제거하고, 엔티티를 디코딩하고, 공백을 축약하고, 비어 있지 않은 제목을 추가합니다	—	—	내부 상태를 변경합니다
`AutoTocCollector::assignSequentialPages()`	`int $startPage = 1`	첫 번째 이후 각 레벨 0 제목에서 페이지를 진행합니다	`list<TocHeading>`	—	플레이스홀더 번호 매기기만 수행합니다
`AutoTocCollector::assignPageNumbers()`	`array<int,int> $pageMap`	인덱스-페이지 맵을 적용합니다. 매핑되지 않은 인덱스는 현재 페이지를 유지합니다	`list<TocHeading>`	—	호출자가 제공한 실제 페이지
`AutoTocCollector::getHeadings()`	—	수집된 제목을 반환합니다	`list<TocHeading>`	—	—
`AutoTocCollector::count()`	—	수집된 제목의 개수	`int`	—	—
`AutoTocCollector::reset()`	—	수집된 제목을 지웁니다	—	—	스캔 간에 컬렉터를 재사용합니다
`AutoTocRenderer::render()`	`list<TocHeading> $headings`, `?AutoTocConfig $config = null`	깊이로 필터링하고, 페이지네이션하고, 페이지당 하나의 콘텐츠 스트림을 방출합니다	`list<string>`	—	모든 제목이 필터링되면 `[]`를 반환합니다
`AutoTocConfig::__construct()`	14개의 타입 매개변수 (title, depth, fonts, spacing, margins, colors, page size)	불변 구성 캐리어	—	—	Readonly. `ChartColor` 색상은 기본값이 검정입니다
`AutoTocConfig::default(), ::landscape(), ::letter()`	—	A4 세로, A4 가로, US Letter 프리셋	`self`	—	정적 팩토리
`AutoTocConfig::withTitle(), ::withMaxDepth(), ::withFontSize(), ::withDotLeader(), ::withPageNumbers(), ::withIndentPerLevel()`	각각 하나의 값	해당 필드가 변경된 새 인스턴스를 반환합니다. `withMaxDepth()`는 1–6으로 클램핑합니다	`self`	—	플루언트, 비변경
`AutoTocConfig::contentWidth()`	—	`pageWidth - 2 * leftMargin`	`float`	—	파생값
`AutoTocConfig::lineSpacing()`	—	`fontSize * lineHeight`	`float`	—	파생값
`AutoTocConfig::entriesPerPage()`	—	`max(1, floor((pageHeight - 2topMargin - 2titleFontSize) / lineSpacing))`	`int`	—	항상 ≥ 1
`TocHeading::__construct()`	`string $title`, `int $level`, `?int $pageNumber = null`, `float $y = 0.0`	불변 제목 값 객체	—	—	Readonly. 레벨 0 = H1
`TocHeading::withPageNumber(), ::withY(), ::withPosition()`	페이지 번호 및/또는 Y 좌표	위치 필드가 변경된 새 인스턴스를 반환합니다	`self`	—	플루언트, 비변경
`TocHeading::hasPageNumber()`	—	페이지 번호가 할당되면 참	`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()는 동일한 레벨의 균형 잡힌 열기/닫기 태그를 요구하는 한정된(bounded) 패턴(대소문자 구분 없음, dot-matches-newline)으로 <h1>–<h6>을 매칭합니다. 각 일치의 내부 콘텐츠는 태그가 제거되고, 엔티티가 디코딩되며 (ENT_QUOTES | ENT_HTML5, UTF-8), 공백이 축약됩니다. 빈 결과는 드롭됩니다. level은 태그 번호에서 1을 뺀 값이므로 H1은 레벨 0입니다. maxDepth보다 깊은 태그는 건너뜁니다. extract()는 생성, 스캔, 읽기를 하나로 묶은 단일 호출 팩토리입니다.

페이지 번호 할당

두 가지 명시적 전략이 있으며, 둘 다 호출자 주도입니다.

assignSequentialPages($startPage)는 첫 번째 항목 이후 레벨 0 제목에 도달하면 페이지 카운터를 진행한 다음 모든 제목에 스탬프를 찍습니다.
assignPageNumbers($pageMap)는 인덱스-페이지 맵을 적용합니다. 매핑되지 않은 인덱스는 기존 페이지 번호를 유지합니다.

어느 전략도 레이아웃이 완료된 문서를 검사하지 않습니다.

렌더링 및 페이지네이션

AutoTocRenderer::render()는 level이 maxDepth보다 작은 제목을 유지하고, 남는 것이 없으면 []를 반환한 다음, 나머지를 AutoTocConfig::entriesPerPage() 크기의 청크로 분할합니다. 각 청크는 하나의 콘텐츠 스트림 문자열이 됩니다. 항목마다 들여쓰기는 leftMargin + level * indentPerLevel입니다. 폰트 크기는 레벨당 0.5 pt씩 줄어들고 6.0 pt에서 하한이 적용됩니다. 레벨 0은 볼드 폰트 키를, 더 깊은 레벨은 일반 키를 사용합니다. 페이지 번호가 활성화되어 있고 존재하면, 선택적 점 리더가 간격을 채우고 번호는 오른쪽 정렬됩니다. 제목과 모든 항목 문자열은 ISO 32000-2:2020 §9.4에 따라 Tj 연산자로 표시되며, 각 문자열은 §7.3.4.2에 따라 PDF 리터럴 문자열 구문에 맞게 이스케이프됩니다. 동일한 HTML과 구성은 안정적인 제목과 연산자를 산출합니다.

엣지 케이스 및 실패 모드

형식이 잘못된 제목 마크업은 수집되지 않습니다. 일치하는 </h2>가 없는 닫히지 않은 <h2>는 균형 쌍 패턴에 실패하여 건너뜁니다.
태그 제거와 트리밍 후 비어 있는 제목 텍스트는 드롭됩니다.
maxDepth는 컬렉터 생성자와 AutoTocConfig::withMaxDepth() 양쪽에서 1–6으로 클램핑됩니다. 범위를 벗어난 값은 거부되지 않고 보정됩니다.
페이지 번호는 호출자가 제어합니다. 제목이 실제로 놓이는 페이지를 발견하는 내부 레이아웃 패스가 없으므로, 모듈은 라이브 상호 참조를 해석할 수 없습니다.
이 모듈은 예외를 발생시키지 않습니다. render()는 모든 제목이 깊이로 필터링되면 빈 배열을 반환하며, 빈 입력에 대해 절대 예외를 던지지 않습니다.
크기 계산은 max(1, …) 하한으로 수렴하므로, entriesPerPage()는 항상 최소 1이며 페이지네이션은 항상 진행됩니다.
렌더러는 그릴 수 있는 연산자만 생성합니다. 호출자는 반환된 스트림을 실제 페이지에 배치하고 /TocFont, /TocBoldFont, /TocTitleFont 리소스를 제공합니다.

FIPS 모드 동작

이 모듈에서는 암호 연산이 발생하지 않으므로 FIPS 모드 특정 동작이 없습니다. 여기서는 난수, 해싱, 서명을 소비하는 것이 없습니다.

적합성

주장	표준	절
TOC 제목과 항목 텍스트가 `Tj` 텍스트 표시 연산자로 표시됨	ISO 32000-2:2020	§9.4
방출된 문자열이 PDF 리터럴 문자열로 이스케이프되며, 백슬래시는 두 배로, 괄호는 이스케이프됨	ISO 32000-2:2020	§7.3.4.2
PDF `/Outlines` 트리 또는 명명된 대상 링크	—	빌드되지 않음 (콘텐츠 스트림 연산자만)
라이브 문서 상호 참조 해석	—	지원되지 않음 (호출자 제공 페이지 번호)

모든 절은 의역되었으며, 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이므로 각 위더는 새 인스턴스를 반환합니다.
실제 페이지 번호는 자체 레이아웃 패스에서 assignPageNumbers()로 할당하세요. assignSequentialPages()는 플레이스홀더만 산출합니다.
entriesPerPage(), lineSpacing(), contentWidth()는 구성의 순수 파생값입니다. 렌더링 전에 레이아웃 크기를 미리 계산하려면 이들을 호출하세요.
getHeadings(), count(), reset()는 스캔 간에 컬렉터의 누적 상태를 읽고 지웁니다.

게시 범위

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위를 벗어납니다.

함께 보기

목차 (기능) — 설치, 빠른 시작, 프로덕션 샘플.
Merge — 심층 참조
Template — 심층 참조