إضافة الإشارات المرجعية وجدول المحتويات

لمحة سريعة

تضيف هذه الوصفة إشارات مرجعية على هيئة مخطط مستند هرمي. يعرض تطبيق القراءة هذه المدخلات في شريط التنقل الجانبي، حيث تعمل كجدول محتويات قابل للنقر. يتحكم مستوى صحيح في عمق التداخل. تتبع الوصفة examples/12-bookmarks-and-toc.php.

يسمي ⁨ISO 32000-2⁩ هذا الهيكل مخطط المستند: شجرة من عناصر المخطط تعمل كجدول محتويات مرئي.

التثبيت

composer require nextpdf/core:^3

لا يلزم أي امتداد اختياري. واجهة برمجة الإشارات المرجعية مستقرة منذ 1.0.0 وتعمل عبر مصفوفة التوافق الخلفي 8.1–8.4.

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

bookmark($title, $level, $y) يضيف عنصر مخطط واحدًا مرتبطًا بالصفحة الحالية. يستخدم الربط موضع ⁨Y⁩ الحالي ما لم تمرر قيمة ⁨Y⁩ صريحة. يحدد $level عمق التداخل: المستوى 0 فصل في أعلى الهرم، والمستوى 1 قسم ضمن أحدث عنصر من المستوى 0، وهكذا. يبني المحرك شجرة المخطط نيابةً عنك. يربط ⁨ISO 32000-2⁩ العناصر في سلسلة عبر Prev/Next عند كل مستوى ويداخِلها عبر First/Last، مع مدخل Outlines في الفهرس بوصفه الجذر.

يحمل كل عنصر وجهةً، فينتقل القارئ إلى الصفحة الصحيحة عند النقر على الإشارة المرجعية. ينص ⁨ISO 32000-2⁩ §12.3.2 على جواز ربط الوجهات بعناصر المخطط. يغذّي الاستدعاء نفسه أيضًا أداة إنشاء جدول المحتويات في ⁨NextPDF⁩، فيبقى المخطط وجدول المحتويات المعروض متزامنين.

سطح واجهة البرمجة

يُولَّد سطح واجهة البرمجة من ⁨PHPDoc⁩. تعتمد هذه الوصفة على دالة واحدة:

• bookmark(string $title, int $level = 0, float $y = -1): static — يضيف عنصر مخطط عند $level مرتبطًا بالصفحة الحالية. يستخدم $y = -1 موضع ⁨Y⁩ الحالي للمؤشر. مرر قيمة ⁨Y⁩ غير سالبة لتثبيت وجهة دقيقة.

نموذج التعليمات البرمجية — بداية سريعة

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();

$doc->addPage();
$doc->bookmark('Chapter 1', level: 0);
$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Chapter 1', newLine: true);

$doc->bookmark('Section 1.1', level: 1); // nested under Chapter 1
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Section body.');

$doc->addPage();
$doc->bookmark('Chapter 2', level: 0);
$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Chapter 2', newLine: true);

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/bookmarks.pdf');

نموذج التعليمات البرمجية — للإنتاج

يحترم هذا المثال الكامل الجاهز للاختبار NEXTPDF_COOKBOOK_OUTPUT ولا يُدخل أي عشوائية من تلقاء نفسه.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Bookmarks and Navigation');
$doc->setPrintHeader(false);
$doc->setPrintFooter(false);
$doc->setAutoPageBreak(true, margin: 25);

// Chapter 1
$doc->addPage();
$doc->bookmark('Chapter 1: Introduction', level: 0);
$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Chapter 1: Introduction', newLine: true);
$doc->ln(3);

$doc->bookmark('What is NextPDF?', level: 1);
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'What is NextPDF?', newLine: true);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'NextPDF is a modern PDF 2.0 library for PHP 8.4+. '
    . 'It generates standards-targeting documents with typography, '
    . 'graphics, and signatures.');
$doc->ln(5);

$doc->bookmark('Key Features', level: 1);
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Key Features', newLine: true);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'HTML rendering, barcodes, PAdES signatures, '
    . 'and a worker-safe architecture.');

// Chapter 2
$doc->addPage();
$doc->bookmark('Chapter 2: Getting Started', level: 0);
$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Chapter 2: Getting Started', newLine: true);
$doc->ln(3);

$doc->bookmark('Installation', level: 1);
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Installation', newLine: true);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Install via Composer: composer require nextpdf/core');

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/bookmarks.pdf';
$doc->save($out);

echo "Created bookmarks.pdf with a 2-level outline\n";

الحالات الحدية والمزالق

• تخطّي المستويات. قد يظهر الانتقال من المستوى 0 إلى المستوى 2 دون مستوى 1 بينهما بصورة مشوّهة في بعض القارئات. زِد المستوى بمقدار واحد على الأكثر كل مرة.
• الإشارة المرجعية قبل المحتوى. استدعِ bookmark() عند النقطة التي تريد أن تكون الوجهة عندها. في معظم الحالات، ضع الاستدعاء قبل العنوان مباشرةً. أما الاستدعاء الموضوع بعد العنوان فيضبط الوجهة أسفله بقليل.
• قيمة ⁨Y⁩ صريحة للوجهات الدقيقة. مع $y = -1، تكون الوجهة هي موضع ⁨Y⁩ الحالي للمؤشر. مرر قيمة ⁨Y⁩ صريحة للحصول على وجهة ثابتة. على سبيل المثال، تُثبّت قيمة ⁨Y⁩ الصريحة أعلى القسم بصرف النظر عن مقدار المحتوى الذي يسبقه.
• دعم المخطط شامل، لكن طريقة العرض تتفاوت. قد تعرض القارئات المخطط مطويًا أو موسّعًا. لا تستطيع هذه الواجهة البرمجية فرض حالة مفتوحة أو مغلقة لكل عنصر.

الأداء

يُلحق كل استدعاء لـ bookmark() عنصر مخطط واحدًا ومدخل جدول محتويات واحدًا؛ وهذا عمل بتعقيد ⁨O⁩(1). تكتمل شجرة المخطط مرة واحدة عند save(). تبقى مئات الإشارات المرجعية ضمن ميزانية 2000 ⁨ms⁩ / 64 ⁨MB⁩ بهامش واسع.

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

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

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
مخطط المستند شجرة من عناصر المخطط تعمل كجدول محتويات مرئي.	⁨ISO 32000-2⁩	§12.3.3
تترابط عناصر المخطط في سلسلة عبر Prev/Next وتتداخل عبر First/Last.	⁨ISO 32000-2⁩	§12.3.3
قاموس المخطط هو مدخل Outlines في الفهرس.	⁨ISO 32000-2⁩	§7.7.2
يجوز ربط الوجهات بعناصر المخطط.	⁨ISO 32000-2⁩	§12.3.2

ملف قابلية إعادة الإنتاج — هيكلي. يتغير /ID في المقطورة وذرات التاريخ مع كل عملية حفظ، لذلك يجرّد إطار الاختبار تلك الذرات ويقارن الهيكل المُسوّى بواسطة ⁨qpdf⁩. تصف هذه الوصفة كيف يُنتج ⁨NextPDF⁩ ذلك الهيكل، ولا تؤكد مطابقة ⁨ISO 32000-2⁩ كادعاء شامل.

السياق التجاري

غير منطبق. مخطط المستند وجدول المحتويات ميزتان في ⁨Core⁩ دون أي بوابة ⁨Premium⁩.

انظر أيضًا

• وحدة التنقل
• بناء مستند متعدد الصفحات
• الروابط والتعليقات التوضيحية