التنقّل: التعليقات التوضيحية والروابط والمخططات التفصيلية والإجراءات والمرفقات

لمحة سريعة

تُنشئ وحدة التنقّل الطبقة التفاعلية في صيغة المستندات المحمولة (⁨PDF⁩). وتشمل التعليقات التوضيحية، وتعليقات الروابط التوضيحية وعناوين ⁨URL⁩، والمخطط التفصيلي للمستند (العلامات المرجعية)، وجدول المحتويات، والإجراءات وسلاسل المُشغِّلات، وانتقالات الصفحات، ومرفقات الملفات المُضمَّنة مع علاقات الملفات المرتبطة بها.

التثبيت

composer require nextpdf/core:^3

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

يُعرِّف ⁨ISO 32000-2⁩ §12 الميزات التفاعلية في مستند ⁨PDF⁩: التعليقات التوضيحية والإجراءات والوجهات والمخطط التفصيلي للمستند. تُمثِّل هذه الوحدة تلك الطبقة للمُحرِّك. تجمع فئات المدير القصد، وتحمل كائنات القيمة البيانات التي تُصدِرها تلك المُديرات.

AnnotationManager هو أوسع نقطة دخول. فهو يضيف التعليقات التوضيحية النصية، والنص الحر، والخط، والمربع، والدائرة، والمضلَّع، والخط المتعدد، والحبر، وتعليقات تعليم النص (التظليل والتسطير). وقد صُمِّم لتحمّل المُدخلات العدائية: يعود أي نوع فرعي غير معروف لتعليق توضيحي إلى افتراضي آمن، ويُستبدل اسم أيقونة ليس رمز اسم ⁨PDF⁩ صالحًا، ويجب أن تأتي قيم QuadPoints لتعليم النص كمضاعف لثمانية أعداد عشرية وإلا أُسقِطت. هذه الفحوص دفاعات ضد حقن ⁨PDF⁩، وليست مجرد وسائل تيسير للتحقق. LinkManager يتولّى الروابط الداخلية والوجهات المُسمّاة والتعليقات التوضيحية الخاصة بـ ⁨URL⁩. وهو يُخصِّص كائنات التعليقات التوضيحية مُسبقًا حتى يتمكّن ⁨Writer⁩ من الإشارة إليها قبل التسلسل.

BookmarkManager وTocBuilder يُنشئان التسلسل الهرمي للتنقّل. المخطط التفصيلي للمستند هو شجرة العلامات المرجعية التي يعرضها العارض في الشريط الجانبي. TocBuilder يُصيِّر جدول محتويات داخل الصفحة، ويمكنه استخدام FontMetrics لتخطيط ⁨leader/width⁩. OutlineAutoGenerator يشتقّ مخططًا تفصيليًا من بنية المستند.

يُمثِّل التسلسل الهرمي Action ضمن NextPDF\Navigation\Action السلوك المدفوع بالمُشغِّلات: ⁨GoTo⁩ (البعيد والمُضمَّن)، والإطلاق، والمُسمّى، والإخفاء، و⁨reset/submit⁩ النموذج، وتعيين حالة المحتوى الاختياري. أما إجراء تصيير التعليق التوضيحي للشاشة في §13 فمؤجَّل؛ فهو عمل مستقبلي ولم يُوصَّل بعد. لا تعتمد عليه بوصفه إجراءً مدعومًا. Action::withNext() يُنشئ سلسلة الإجراءات التي تعمل لحدث مُشغِّل واحد. PageTransition يُمثِّل انتقال عرض تقديمي. FileAttachment يُضمِّن ملفًا من مسار أو سلسلة بايتات ويُعلِّمه بـ AFRelationship (تعداد علاقة الملف المرتبط). وهو يُعيد FileAttachmentResult ويكتب عبر writeAttachments(). مُديرات ⁨Core⁩ الأساسية هي @since 1.0.0. والتسلسل الهرمي للإجراءات هو @since 2.1.0. وأُضيف مُنشئ FileAttachment وAFRelationship عند @since 1.8.0 / @since 1.1.0.

سطح واجهة برمجة التطبيقات (⁨API⁩)

الفئة	الأعضاء الرئيسيون	الدور
`AnnotationManager`	`addAnnotation()`، `addFreeText()`، `addLine()`، `addSquare()`، `addCircle()`، `addPolygon()`، `addInk()`، `addHighlight()`، `addUnderline()`	مُنشئ تعليقات توضيحية بمدخلات آمنة ضد الحقن (`@since 1.0.0`)
`LinkManager`	`addLink()`، `setLink()`، `setDestination()`، `addLinkAnnotation()`، `addUrlAnnotation()`، `preallocateAnnotationObjects()`	الروابط الداخلية والوجهات المُسمّاة والتعليقات التوضيحية لـ ⁨URL⁩ (`@since 1.0.0`)
`BookmarkManager`	`addBookmark()`، `hasBookmarks()`، `write()`	شجرة المخطط التفصيلي للمستند (العلامات المرجعية) (`@since 1.0.0`)
`TocBuilder`	`addEntry()`، `hasEntries()`، `render()`، `getEntries()`	جدول محتويات داخل الصفحة (`@since 1.0.0`)
`Action` (واجهة)	`subtype()`، `toDictionary()`، `withNext()`، `nextChain()`	إجراء مرتبط بمُشغِّل + سلسلة إجراءات (`@since 2.1.0`)
`PageTransition`	`toDict()`، `toInlineDict()`	انتقال صفحة العرض التقديمي (`@since 1.2.0`)
`FileAttachment`	`embedFile()`، `embedFileFromString()`، `hasAttachments()`، `getCount()`، `writeAttachments()`	مرفقات الملفات المُضمَّنة (`@since 1.0.0`)
`AFRelationship` (تعداد)	`toPdfName()`	علاقة الملف المرتبط (`@since 1.1.0`)
`AnnotationFlags`	`with()`، `without()`، `has()`، `toInt()`	مجموعة أعلام تعليق توضيحي غير قابلة للتغيير (`@since 1.2.0`)

شغِّل composer docs:generate-api-php -- --module=Navigation لإنشاء جدول ⁨PHPDoc⁩ الكامل.

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

examples/12-bookmarks-and-toc.php يُنشئ المخطط التفصيلي للمستند عبر الواجهة عالية المستوى التي تُغلِّف BookmarkManager. استخدم المدير مباشرةً بهذه الطريقة:

<?php

declare(strict_types=1);

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

use NextPDF\Navigation\BookmarkManager;

$bookmarks = new BookmarkManager();
$bookmarks->addBookmark(title: 'Chapter 1', level: 0, pageIndex: 0);
$bookmarks->addBookmark(title: '1.1 Overview', level: 1, pageIndex: 0);
$bookmarks->addBookmark(title: 'Chapter 2', level: 0, pageIndex: 4);

if ($bookmarks->hasBookmarks()) {
    // The Writer calls $bookmarks->write(...) during catalog serialization.
}

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

ضمِّن مرفقًا بعلاقة ملف مرتبط صريحة، ثم تحقّق من النتيجة قبل إنهاء المستند.

<?php

declare(strict_types=1);

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

use NextPDF\Navigation\AFRelationship;
use NextPDF\Navigation\FileAttachment;

$attachments = new FileAttachment();

$attachments->embedFile(
    path: '/srv/invoices/INV-2026-0042.xml',
    description: 'Structured invoice source (Factur-X)',
    afRelationship: AFRelationship::Source,
);

if ($attachments->hasAttachments()) {
    // writeAttachments() is invoked by the Writer with a live ObjectRegistry;
    // getCount() lets the application assert the expected attachment count.
    assert($attachments->getCount() === 1);
}

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

AnnotationManager يُسوِّي المُدخلات العدائية بصمت: يصبح النوع الفرعي غير الصالح هو الافتراضي، وتصبح الأيقونة غير المُسمّاة هي الأيقونة الافتراضية، وتُسقَط قيم QuadPoints المُشوَّهة. يظل التعليق التوضيحي مُنتَجًا؛ تحقّق من المُدخلات في طبقة أعلى إذا كنت تحتاج إلى احترامها بدقة.
يجب تشغيل LinkManager::preallocateAnnotationObjects() قبل أن يُسلسِل ⁨Writer⁩ المراجع، وإلا فلن تُحَلّ أهداف الروابط إلى أي وجهة.
Action::withNext() يُعيد إجراءً جديدًا مع السلسلة المُرفقة؛ تدعم الواجهة التسلسل غير القابل للتغيير، وليس التعديل في المكان.
FileAttachment::writeAttachments() يتطلّب ObjectRegistry نشطًا من ⁨Writer⁩. عند استدعائه بمعزل، يجمع المدير القصد لكنه لا يكتب شيئًا حتى يُشغِّله ⁨Writer⁩.
AnnotationFlags هو مجموعة أعلام غير قابلة للتغيير. with()/without() يُعيدان نسخة جديدة، وتبقى النسخة الأصلية دون تغيير.

الأداء

تراكم التعليقات التوضيحية والروابط والعلامات المرجعية هو ⁨O⁩(⁨n⁩) في عدد العناصر ولا يُجري إعادة تدفّق. يهيمن حجم البايتات المُضمَّنة على تكلفة مرفق الملف المُضمَّن، لا عبء المدير. يبقى حِمل العمل المرجعي الافتراضي داخل ميزانية 1500 ⁨ms⁩ للزمن الجداري / 64 ⁨MB⁩ للذروة. ملف تعريف قابلية إعادة الإنتاج هو structural: تختلف أرقام الكائنات وعنصر /ID في الذيل بين عمليات التشغيل. مستندان لهما نفس قصد التنقّل متساويان بنيويًا، لكنهما ليسا متطابقَين بايتًا ببايت.

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

AnnotationManager يعامل النوع الفرعي للتعليق التوضيحي والأيقونة وQuadPoints بوصفها غير موثوق بها. وهو يتحقّق من كل قيمة مقابل قائمة سماح أو نمط، ويستبدل القيمة السيئة بدلاً من كتابتها. هذا يُغلِق ناقل حقن أسماء ⁨PDF⁩. LinkManager::addUrlAnnotation() يُرمِّز ⁨URL⁩ في إجراء رابط. يبقى ⁨URL⁩ هو حدّ الثقة لدى المستهلك: قد يظل ⁨URL⁩ العدائي صالحًا، لذا طهِّر الوجهات قبل إضافتها. FileAttachment يُضمِّن بايتات عشوائية. قيِّد الحجم المُضمَّن، وعامِل أي مصدر مرفق يُقدِّمه المستخدم بوصفه غير موثوق به. راجع نموذج تهديد المُحرِّك في /modules/core/security/.

المطابقة

البنى التي تُصدِرها هذه الوحدة تتبع ⁨ISO 32000-2⁩ §12 للتعليقات التوضيحية والإجراءات والوجهات والتسلسل الهرمي للمخطط التفصيلي للمستند. مراجع البنود لكل ميزة (أيقونات التعليقات التوضيحية §12.5.6.4، وQuadPoints لتعليم النص §12.5.6.10، والإجراءات §12.6) مُوثَّقة ضمنيًا في src/Navigation/ ومُختبَرة بواسطة tests/Unit/Navigation/. هذه حقائق تنفيذ، وليست بيانًا بمطابقة ⁨PDF 2.0⁩ من طرف إلى طرف. تتحقّق مجموعتا الأوراكل والمرجع الذهبي الموصوفتان في /modules/core/conformance/ من المطابقة الكاملة للمستند.

انظر أيضًا

وحدة ⁨Document⁩
وحدة ⁨Multimedia⁩ — كائنات التصيير التي يُشغِّلها إجراء التصيير.
وحدة ⁨Writer⁩ — تُسلسِل بنى التنقّل.
نظرة عامة على المطابقة
نموذج أمان المُحرِّك