Pro الإصدار

جدول المحتويات

لمحة سريعة

يجمع NextPDF\Pro\Toc عناوين ⁨H1⁩–⁨H6⁩ من ⁨HTML⁩ ويُصيِّر جدول محتويات مُرقَّمًا متعدّد المستويات بصفته مُعامِلات تدفّق محتوى ⁨PDF⁩. وأرقام الصفحات يُورِّدها المُستدعي (أو عناصر نائبة تسلسلية)؛ ولا تحلّ الوحدة الإحالات المرجعية الحيّة في المستند.

التوفّر والترخيص

تتوفّر هذه القدرة في ‏⁨NextPDF Pro⁩ (nextpdf/pro) وتُفعَّل عبر غلاف ترخيص من فئة ⁨Pro⁩. والنشر بلا ذلك الاستحقاق لا يُحمّل أصناف القدرة. وتُحمَّل أصناف ⁨Toc⁩ متى ثُبِّتت nextpdf/pro؛ ولا تحجب أي علامة قدرة في وقت التشغيل هذه الوحدة. قارِن الإصدارات واحصل على ترخيص.

التثبيت

composer require nextpdf/pro:^3

نظرة مفاهيمية عامة

لسير العمل طوران:

الجمع. يمسح AutoTocCollector::extract($html, maxDepth) نصّ ⁨HTML⁩ بحثًا عن وسوم <h1>–<h6> حتى حدّ العمق، ويجرّد العلامات الداخلية، ويفكّ الكيانات، ويُسوّي المسافات البيضاء، ويُصدِر كائنات قيمة TocHeading (المستوى 0 = ⁨H1⁩). ويستطيع إسناد أرقام صفحات تسلسلية أو تطبيق خريطة فهرس إلى صفحة يقدّمها المُستدعي.
التصيير. يُنتِج AutoTocRenderer::render($headings, $config) سلسلة تدفّق محتوى ⁨PDF⁩ واحدة لكل صفحة جدول محتويات، مع إزاحة لكل مستوى، ورؤوس نقطية اختيارية، وأرقام صفحات اختيارية. ويُصدَر كل سطر ظاهر بصفته عملية إظهار نص Tj وفق ⁨ISO 32000-2:2020 §9.4⁩.

AutoTocConfig كائن قيمة غير قابل للتغيير مُهيَّأ انسيابيًا يتحكّم في العنوان، والعمق، والخطوط، والتباعد، والهوامش، والألوان، وحجم الصفحة، وما إذا كانت الرؤوس النقطية وأرقام الصفحات تُعرَض.

لماذا يعمل بهذه الطريقة

القرار الحامل هو أنّ الوحدة لا تختلق أبدًا رقم صفحة لا تستطيع معرفته. فالصفحات الهدف الحقيقية تعتمد على المستند المُخطَّط نهائيًا، وهو ملك المُستدعي؛ وأي تخمين سينحرف بصمت كلّما تغيّر الترقيم. لذا يبقى الجمع والتصيير منفصلين عن التخطيط. يُصدِر AutoTocCollector عناوين بصفحات فارغة أو نائبة؛ ولا تصل أرقام الصفحات الحقيقية إلّا عبر خريطة assignPageNumbers() يقدّمها المُستدعي. ثم يُنتِج التصيير مُعامِلات تدفّق محتوى بسيطة، تاركًا وضع الصفحة للمُستدعي. فتبقى النتيجة حتمية وصادقة: تُصرّح الوحدة بما لا تعرفه بدل اختلاقه.

خلفية التصميم: واجهة برمجة ترفض التخمين.

عقد السلوك

المُدخَل. ⁨HTML⁩ (الجمع) وقائمة TocHeading (التصيير).
المخرَج. list<TocHeading> من الجمع؛ وlist<string> من مُعامِلات تدفّق محتوى ⁨PDF⁩ (واحدة لكل صفحة جدول محتويات) من التصيير.
أرقام الصفحات. إمّا مُسنَدة تسلسليًا، أو مُورَّدة عبر خريطة فهرس إلى صفحة، أو متروكة فارغة. ولا تحسب الوحدة الصفحات الهدف الحقيقية من مستند مُخطَّط؛ ولا تحلّ الإحالات المرجعية.
العمق. يُقيَّد maxDepth ضمن 1–6. وتُتخطّى العناوين الأعمق من العمق المُهيَّأ.
الحتمية. لنفس ⁨HTML⁩ والإعداد، تكون العناوين المُجمَّعة والمُعامِلات المُصيَّرة مستقرّة.

سطح واجهة برمجة التطبيقات العامة

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 عند الجامع والإعداد كليهما؛ والقيم خارج المدى تُصحَّح، لا تُرفَض.
أرقام الصفحات عناصر نائبة ما لم يورِّد المُستدعي خريطة حقيقية؛ ولا تشغّل الوحدة مرور تخطيط لاكتشاف الصفحات الهدف الحقيقية.
يُصدِر المُصيِّر مُعامِلات تدفّق محتوًى لوضعها على صفحة؛ ويتحمّل المُستدعي مسؤولية إضافة تلك الصفحات إلى المستند.

الأداء

الجمع مرور تعبير نمطي واحد على ⁨HTML⁩. والتصيير خطّي في عدد العناوين، مُرقَّم بـentriesPerPage(). راجِع performance_budget.

ملاحظات الأمان

يُمسَح ⁨HTML⁩ بتعبير عناوين نمطي محدود وبتجريد الوسوم؛ ولا يُنفَّذ أي ⁨HTML⁩ ولا تُتبَع أي مراجع خارجية. ويُهرَّب النص المُصيَّر لصياغة سلاسل تدفّق المحتوى.

المطابقة

Claim	Spec clause	Status
تُصدَر أسطر جدول المحتويات بصفتها عمليات إظهار نص `Tj`	ISO 32000-2:2020 §9.4	مُتحقَّق منها (مجموعة اختبارات الوحدة)
حلّ الإحالات المرجعية الحيّة في المستند	—	غير مدعوم (أرقام صفحات يقدّمها المُستدعي)

تراجُع النواة / البديل

لا يوجد مولّد جدول محتويات في ⁨Core⁩. وعادةً يأتي ⁨HTML⁩ مصدرُ العناوين من طبقة ⁨HTML⁩ في ⁨Core⁩. راجِع /modules/core/html/.

ملاحظة حدّ ⁨Enterprise⁩

تجمع هذه الوحدة العناوين وتُصيِّر مُعامِلات جدول المحتويات. ولا تؤدّي حلّ الإحالات المرجعية على نطاق المستند، ولا توليد الفهرس، ولا مزامنة شجرة العلامات المرجعية؛ فتلك الشؤون خارج النطاق.

حدّ النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح واجهة البرمجة العامة المدعوم فقط. أمّا مسارات فضاءات الأسماء الداخلية، وأصناف المساعدة، وجداول الآليات، وأسماء ملفّات كتيّبات التشغيل، وبادئات التذاكر، فخارج النطاق.