جدول المحتويات — مرجع متعمّق

لمحة سريعة

هذه الصفحة هي المرجع على مستوى العقد لوحدة ⁨Toc⁩ في ⁨NextPDF Pro⁩، أي NextPDF\Pro\Toc. يمسح AutoTocCollector نصّ ⁨HTML⁩ بحثًا عن عناوين ⁨H1–H6⁩ ويُصدِر كائنات القيمة TocHeading. ويُرقِّم AutoTocRenderer تلك العناوين ويُصيِّر كل صفحة من جدول المحتويات بوصفها مُعامِلات تدفّق محتوى ⁨PDF⁩. وAutoTocConfig هو تهيئة التصيير غير القابلة للتغيير. أرقام الصفحات يوفّرها المُستدعي أو تكون عناصر نائبة تسلسلية؛ ولا تحلّ الوحدة الإحالات المرجعية الحيّة داخل المستند. تعرض هذه الصفحة واجهة برمجة التطبيقات العامة، وعقد السلوك القابل للملاحظة، وأنماط الإخفاق. أما الإعداد الموجّه للمهام والعيّنات فيوجدان في صفحة قدرة جدول المحتويات.

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

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

لا تحجب أي علامة قدرة في وقت التشغيل هذه الوحدة. وأصناف ⁨Toc⁩ قابلة للاستخدام كلما كان nextpdf/pro مُثبَّتًا ومُرخَّصًا.

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

الرمز	المُعامِلات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يُخفِق بـ	ملاحظات
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 مُعامِلًا مُنمَّطًا (العنوان، العمق، الخطوط، التباعد، الهوامش، الألوان، حجم الصفحة)	حامل تهيئة غير قابل للتغيير	—	—	للقراءة فقط؛ ألوان 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 - 2*topMargin - 2*titleFontSize) / lineSpacing))	int	—	دائمًا ≥ 1
TocHeading::__construct()	string $title، int $level، ?int $pageNumber = null، float $y = 0.0	كائن قيمة عنوان غير قابل للتغيير	—	—	للقراءة فقط؛ المستوى 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() الوسوم <h1>–<h6> بنمط محدود (غير حسّاس لحالة الأحرف، مع جعل النقطة تطابق السطر الجديد) يشترط تطابق وسمَي فتح وإغلاق متوازنين من المستوى ذاته. ويُجرَّد المحتوى الداخلي لكل مطابقة من الوسوم، وتُفكَّك كياناته (ENT_QUOTES | ENT_HTML5، ⁨UTF-8⁩)، وتُجمَع مسافاته البيضاء. وتُسقَط النتائج الفارغة. وlevel هو رقم الوسم ناقص واحد، فيكون ⁨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 مفتاح الخط العريض، وتستخدم المستويات الأعمق المفتاح العادي. وعند تفعيل أرقام الصفحات ووجودها، يملأ مُوجِّه نقطي اختياري الفجوة ويُحاذى الرقم إلى اليمين. ويُظهَر العنوان وكل سلسلة مُدخَل بمُعامِل Tj وفق ⁨ISO 32000-2:2020⁩ §⁨9.4⁩، وتُهرَّب كل سلسلة لبنية سلاسل ⁨PDF⁩ الحرفية وفق §7.3.4.2. وتُنتِج نفس ⁨HTML⁩ والتهيئة عناوين ومُعامِلات مستقرة.

الحالات الحدّية وأنماط الإخفاق

• لا تُجمَع علامات العناوين المشوَّهة. فالوسم <h2> غير المُغلَق بلا </h2> مطابِق يُخفِق في نمط الزوج المتوازن ويُتخطّى.
• يُسقَط نصّ العنوان الفارغ بعد تجريد الوسوم والاقتطاع.
• يُقيَّد maxDepth ضمن 1–6 في كل من مُنشئ المُجمِّع وAutoTocConfig::withMaxDepth()؛ وتُصحَّح القيم خارج المدى، لا تُرفَض.
• أرقام الصفحات يتحكّم بها المُستدعي. ولا يوجد مرور تخطيط داخلي يكتشف الصفحة الفعلية التي يقع فيها عنوان، فلا تستطيع الوحدة حلّ الإحالات المرجعية الحيّة.
• لا تُطلِق الوحدة أي استثناءات. ويُعيد render() مصفوفة فارغة عندما تُرشَّح كل العناوين خارجًا حسب العمق؛ ولا يرمي أبدًا على مُدخَل فارغ.
• ينهار التحجيم إلى أرضية max(1, …)، فيكون entriesPerPage() دائمًا 1 على الأقل ويُحرِز الترقيم تقدّمًا دائمًا.
• يُنتِج المُصيِّر مُعامِلات قابلة للرسم فقط. ويضع المُستدعي التدفّقات المُعادة على صفحات حقيقية ويوفّر موارد /TocFont و/TocBoldFont و/TocTitleFont.

سلوك وضع ⁨FIPS⁩

لا تجري أي عملية تشفير في هذه الوحدة، فلا يوجد سلوك خاص بوضع ⁨FIPS⁩. ولا يستهلك أي شيء هنا العشوائية أو التجزئة أو التوقيع.

المطابقة

الادّعاء	المعيار	البند
يُظهَر عنوان جدول المحتويات ونصّ المُدخَلات بمُعامِل إظهار النص Tj	⁨ISO 32000-2:2020⁩	§9.4
تُهرَّب السلاسل المُصدَرة بوصفها سلاسل ⁨PDF⁩ حرفية، مع مضاعفة الخط المائل العكسي وتهريب الأقواس	⁨ISO 32000-2:2020⁩	§7.3.4.2
شجرة /Outlines في ⁨PDF⁩ أو روابط وجهات مُسمّاة	—	لا تُبنى (مُعامِلات تدفّق محتوى فقط)
حلّ الإحالات المرجعية الحيّة في المستند	—	غير مدعوم (أرقام صفحات يوفّرها المُستدعي)

جميع البنود مُعاد صياغتها؛ ولا يُعيد ⁨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()، ثم سلسِل مُعدِّلات الإنشاء. والكائن للقراءة فقط، فيُعيد كل مُعدِّل نسخة جديدة.
• أسنِد أرقام صفحات حقيقية بـassignPageNumbers() من مرور تخطيطك الخاص؛ ولا يُنتِج assignSequentialPages() إلا عناصر نائبة.
• ‏entriesPerPage() وlineSpacing() وcontentWidth() اشتقاقات محضة من التهيئة؛ استدعِها لتحديد حجم التخطيط مسبقًا قبل التصيير.
• ‏getHeadings() وcount() وreset() تقرأ وتمسح حالة المُجمِّع المتراكمة بين عمليات المسح.

حدود النشر

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

انظر أيضًا

• جدول المحتويات (القدرة) — التثبيت، والبدء السريع، وعيّنات الإنتاج.
• ‏⁨Merge⁩ — مرجع متعمّق
• ‏⁨Template⁩ — مرجع متعمّق