إنشاء طبقات محتوى اختيارية (OCG)

نظرة سريعة

غلّف المحتوى في مجموعات محتوى اختيارية مسمّاة (⁨OCGs⁩)، والتي تُسمّى غالبًا طبقات. يستطيع قارئ ⁨PDF⁩ تبديل كل طبقة من لوحة الطبقات الخاصة به، مع إبقاء إحدى الطبقات مخفيةً افتراضيًا. تتبع هذه الوصفة examples/26-layers.php.

الـ ⁨OCG⁩ هو قاموس مجموعة محتوى اختيارية وفق ⁨ISO 32000-2⁩ مع Type /OCG. يغلّف ⁨NextPDF⁩ علامات الطبقات بين BDC/EMC ويستخدم وسم المحتوى المُعلَّم OC.

التثبيت

composer require nextpdf/core:^3

لا تحتاج إلى امتداد اختياري. واجهة برمجة تطبيقات الطبقات مستقرة منذ 1.0.0 وتعمل ضمن مصفوفة ⁨backport⁩ لإصدارات 8.1–8.4.

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

تفتح startLayer($name, $visible) مجموعة ⁨OCG.⁩ كل ما ترسمه حتى استدعاء endLayer() المقابل ينتمي إلى تلك المجموعة. $name هو التسمية التي يعرضها قارئ ⁨PDF⁩ في لوحة الطبقات الخاصة به. يتطلب ⁨ISO 32000-2⁩ سمة Name للـ ⁨OCG⁩، وهي السلسلة الموجّهة إلى المستخدم. تمرير $visible: false يسجّل المجموعة في حالة ⁨OFF⁩ ضمن التهيئة الافتراضية، فيُخفيها القارئ إلى أن يفعّلها المستخدم.

الظهور تعاوني ويتوقف على القارئ. بالنسبة إلى قاموس عضوية محتوى اختيارية (⁨OCMD⁩)، تكون سياسة الظهور الافتراضية هي AnyOn. تظهر الطبقة إذا كانت أي مجموعة مُشار إليها في حالة ⁨ON.⁩ الطبقة المخفية مخفيةٌ وفق اصطلاح القارئ فقط. فهي ليست محذوفةً ولا محميةً، وليست تنقيحًا ولا وسيلة ضبط أمني. لإزالة المحتوى، لا ترسمه.

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

يولّد ⁨PHPDoc⁩ سطح واجهة برمجة التطبيقات تلقائيًا. تستخدم هذه الوصفة الدالتين الآتيتين:

• startLayer(string $name, bool $visible = true): static — تفتح مجموعة ⁨OCG⁩ مسمّاة؛ ويجعلها $visible: false مخفيةً افتراضيًا.
• endLayer(): static — تغلق آخر طبقة فُتحت (متوازنة مع startLayer()).

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

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

$doc->startLayer('Content', visible: true);
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 8, 'Always-visible body content.', newLine: true);
$doc->endLayer();

$doc->startLayer('Debug Grid', visible: false); // hidden until toggled
$doc->setDrawColor(200, 200, 200);
for ($x = 0.0; $x <= 210.0; $x += 10.0) {
    $doc->line($x, 0, $x, 297);
}
$doc->endLayer();

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

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

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

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Layer Examples (OCG)');
$doc->addPage();

// Layer 1 — background, visible by default.
$doc->startLayer('Background', visible: true);
$doc->setFillColor(230, 240, 250);
$doc->rect(10, 10, 190, 277, 'F');
$doc->endLayer();

// Layer 2 — watermark, visible by default; can be toggled off.
$doc->startLayer('Watermark', visible: true);
$doc->setFont('helvetica', 'B', 54);
$doc->setTextColor(200, 200, 200);
$doc->startTransform();
$doc->rotate(45, 105, 148);
$doc->setXY(30, 135);
$doc->cell(150, 20, 'DRAFT', align: Alignment::Center);
$doc->stopTransform();
$doc->endLayer();

// Layer 3 — main content, visible by default.
$doc->startLayer('Content', visible: true);
$doc->setTextColor(0);
$doc->setFont('helvetica', 'B', 20);
$doc->setXY(10, 15);
$doc->cell(0, 14, 'Layer Examples (OCG)', newLine: true);
$doc->ln(4);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'This document contains four optional content groups. '
    . "Toggle them in your reader's Layers panel.");
$doc->endLayer();

// Layer 4 — debug grid, hidden by default.
$doc->startLayer('Debug Grid', visible: false);
$doc->setDrawColor(180, 180, 180);
$doc->setLineWidth(0.15);
for ($x = 0.0; $x <= 210.0; $x += 10.0) {
    $doc->line($x, 0, $x, 297);
}
for ($y = 0.0; $y <= 297.0; $y += 10.0) {
    $doc->line(0, $y, 210, $y);
}
$doc->endLayer();

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

echo "Created layers.pdf\n";

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

• وازِن كل startLayer() باستدعاء endLayer(). تترك الطبقة غير المُغلقة BDC معلَّقًا بلا EMC وتجعل بنية المستند تالفة. اقرن كل استدعاء فتح باستدعاء الإغلاق المقابل له.
• الطبقة المخفية ليست محذوفة. يُخفي visible: false المحتوى وفق اصطلاح القارئ فقط. تبقى العلامات وأي نص في الملف وتظل قابلةً للاسترجاع. هذا ليس تنقيحًا. بالنسبة إلى البيانات الحساسة، لا ترسمها.
• يتفاوت دعم لوحة الطبقات. يتطلب التبديل قارئًا يعرض المحتوى الاختياري. قد تعرض مسارات الطباعة والعارضات البسيطة الطبقات المعطّلة افتراضيًا دائمًا أو تخفيها دائمًا.
• التداخل. الطبقات المتداخلة مسموح بها، لكن يظل ظهور كل مجموعة داخلية مستقلًا. لا تفترض أن طبقة خارجية في حالة ⁨OFF⁩ تخفي مجموعة داخلية في حالة ⁨ON⁩ ما لم تربط سياسة عضوية.

الأداء

تضيف كل طبقة قاموس ⁨OCG⁩ واحدًا وزوجًا من BDC/EMC حول علاماتها. العبء الإضافي ضئيل جدًا. تتناسب التكلفة مع المحتوى داخل الطبقات لا مع عدد الطبقات، لذلك يبقى هذا ضمن ميزانية 2000 ⁨ms⁩ / 64 ⁨MB⁩ بهامش مريح.

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

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

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
يحتوي قاموس ⁨OCG⁩ على Type /OCG.	⁨ISO 32000-2⁩	§8.11.2
سمة Name الخاصة بالـ ⁨OCG⁩ هي التسمية المطلوبة الموجّهة إلى المستخدم.	⁨ISO 32000-2⁩	§8.11.2
يُحاط المحتوى الاختياري بين BDC/EMC مع وسم OC.	⁨ISO 32000-2⁩	§8.11.3.2
سياسات ⁨OCMD⁩ هي ⁨AllOn/AnyOn/AnyOff/AllOff⁩ (الافتراضية ⁨AnyOn⁩).	⁨ISO 32000-2⁩	§8.11.4.3

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

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

لا ينطبق. مجموعات المحتوى الاختيارية قدرة من قدرات ⁨Core⁩ بلا أي بوابة ⁨Premium.⁩

انظر أيضًا

• وحدة الرسوميات
• التدرجات والشفافية
• رسم الرسوميات المتجهة